How thatmlopsguy/k8s-homelab works
Main components
a. Developer Workstation
• Local tools: Docker, Kind (Kubernetes-in-Docker), Helm, Kustomize, Kubectl, k9s
• make entrypoints (e.g. make terraform-apply)
b. Code Repository (GitHub)
• Top-level folders:
• terraform/ – IaC to bootstrap and configure the Kind cluster, providers, variables.
• clusters/ – Helm/Kustomize values for “main” cluster and its addons (Cert-Manager, VictoriaMetrics, etc.).
• environments/ – Environment overlays (defaults & addons).
• gitops/ – ArgoCD AppSets and Project definitions to drive GitOps sync of all addons.
• docs/, mkdocs.yaml, requirements/docs.txt – Documentation site.
• CI workflows: .github/workflows/docs.yml, scorecard.yml
c. CI/CD Pipeline (GitHub Actions)
• Docs build & deploy
• Security checks (Checkov, Scorecard)
d. Terraform (IaC)
• terraform/bootstrap – initial cluster setup, ArgoCD installation if enable_gitops_bridge = true.
• terraform/main.tf, providers, variables, locals.
e. Kubernetes (Kind) Cluster
• Control plane & worker nodes (all local)
• Namespaces for addons (cert-manager, keda, dapr, external-secrets, victoria-metrics)
• ArgoCD installed as an in-cluster component (optional)
f. ArgoCD (GitOps Controller)
• Watches the gitops/ directory in the GitHub repo
• Uses AppSets to split and deploy each addon chart in the target cluster
g. Addon Components
• Cert-Manager
• Dapr
• External Secrets
• KEDA
• Victoria-Metrics
h. User / Inspect Tools
• Kubectl / k9s to inspect cluster status
Relationships & interactions
a. Developer → GitHub: Pushes code to branches → triggers CI/CD workflows
b. GitHub Actions → Documentation & Static Analysis → updates docs site, reports findings
c. Developer → Terraform CLI (make terraform-apply):
• Terraform creates Kind cluster (via bootstrap module)
• Optionally installs ArgoCD in the cluster
d. Terraform → Kubernetes API: Applies manifests for cluster provisioning
e. ArgoCD → GitHub Repo: Polls gitops/ paths → generates AppSets → deploys addons into the cluster
f. Developer → Kubectl/k9s: Inspects live cluster, pods, services
Architectural patterns & principles
• Infrastructure as Code: Terraform for cluster provisioning
• GitOps pattern: ArgoCD + AppSets for continuous delivery of Helm/Kustomize manifests
• Layered configuration:
• Base cluster config in clusters/
• Environment overlays in environments/
• GitOps sync in gitops/
• Modular, declarative definitions for addons