README.md

Local Gitops

• Local Gitops
  • Project Objective
  • Resources versioning
    • Avaliable Kubernetes services:
    • Tools required locally
      • Installing requirements (optional)
    • Initializing the repository
    • In case you want to reset the environment

---

Project Objective

The objective of this project is to furnish a streamlined method for establishing your own local cluster, complete with necessary utilities such as an image registry, garbage collectors, ingress configuration with TLS, and monitoring tools

The project employs k3d to build a local cluster. k3d, a lightweight version of k3s, has the capacity to run all cluster components within containers, thus offering a more efficient local simulation alternative to Minikube or similar counterparts. Further, the project installs ArgoCD atop the k3d-created cluster, leveraging this repository as a resource for executing GitOps. It utilizes the code in the apps/ directory to generate and configure cluster resources.

Additionally, a multi-OS tool is configured to establish the DNS forwarding required for accessing cluster resources via hostnames rather than IP addresses. It employs mkcert to facilitate TLS/SSL-enabled requests towards your cluster ingresses, while continuing to operate exclusively on local resources.

Although the process is designed to be fully automated, users can delve into tasks to comprehend its operations. Taskfiles are easy to digest and they simply illustrate the commands executed at each automation phase.

Resources versioning

- Kubernetes Version: v1.27.4-k3s1
- ArgoCD Version: v2.8.0
- k3d tested using v5.6 with v1alpha5 config file

Avaliable Kubernetes services:

• ArgoCD as the main GitOps tool | Available at argocd.k8s.localhost
• Access to the cluster using Nginx Ingress.
• On-demand databases clusters with Zalando Operator for PostgreSQL | UI available at dbs.k8s.localhost
• Hot-Reload secrets and configmaps to pods using Reloader.
• Mirror resources between namespaces using Reflector.

Tools required locally

• 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 for creating locally based TLS certificates for your ingress proxy
• kubectl | kustomize | helm to apply local commands to the cluster
• jq to manipulate the resulting JSON files and extract the required strings
• 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 Linux/MacOS and Chocolatey for Windows.)}

task tools:install

---

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.

In case you want to reset the environment

Whenever you want to restart from scratch and create a new cluster, just type task again.