Local Gitops

Project goal

This repo was created to give operators a practical way to spin up a local Kubernetes cluster using k3d, which runs k3s in containers - a lightweight version of the standard Kubernetes. You get all the essentials: a private image registry, a GitOps repository and a TLS-secured ingress and it is faster to iterate environments than using Minikube.

The setup uses ArgoCD for GitOps, pulling configurations from the apps directory to manage your resources. For convenience, there's local DNS forwarding so you can access everything by hostname, and mkcert handles TLS certificates automatically to your localhost-based domains.

The repository is automated through Taskfiles, so deployment is straightforward, but you can still dig into individual tasks if you want to understand what's happening under the hood.

Current components versioning

 Kubernetes Version: v1.32.2-k3s1
 ArgoCD Version: v2.14.7
 k3d tested using v5.8.3 v1alpha5 config file

Avaliable Kubernetes services:

• ArgoCD as the main GitOps tool | Available at argocd.k8s.localhost
• Example application | Available at whoami.k8s.localhost
• Access to the cluster using Nginx ingress controller.
• Mirror resources between namespaces using Reflector.

Tools required on the host system

• k3d running atop of either (pick one):
  • Rancher Desktop (Recommended)
  • Docker for Desktop
  • Podman _{(works but requires extra steps)}
• Task as a more modern iteration of the Makefile utility
• mkcert to create local TLS certificates
• kubectl | kustomize | helm to apply local commands to the cluster
• hostctl to create the local domain on your hosts file (optional, but recommended)

---

To list available commands, install Task and run:

task help

Installing requirements (optional)

To install the required tools automatically _{(Requires brew for MacOS and Chocolatey for Windows.)}

task tools

---

Initializing the repository

First: You have to fork this repository.

The task commands will ensure the repository is correctly configured once you run the bootstrapping command.

cd into your forked repository, then run:

task

If you don't have task installed, you can run

 make

which will install the task binary for you and execute the command to run this repository's project by itself.

_{(It might require sudo, please read the commands being executed before doing anything with elevated permissions on your work environment.)}

Where cluster resources are located?

• All PVCs files are configured to be stored in the repository storage/ folder. In case you want backup your environment, simply copy these files to another location, and transfer them back when needed.
• Local SSL/TLS certificates will be stored under the config/tls/ folder. All of them are a part of the .gitignore file, in order to avoid being commited to your repository once created.

How do I reset the environment?

Whenever you want to restart from scratch and create a new cluster, just type task again. This process will destroy the previous cluster and create a new from scratch.