Introduction
Welcome to the Kubernetes Playground Cluster - a home Kubernetes lab using GitOps principles with ArgoCD and Helm.
What Is This?
This is my personal home Kubernetes cluster setup. It contains the complete infrastructure-as-code for a self-managed bare-metal Kubernetes cluster. The setup follows GitOps principles where all cluster configurations are stored in Git and automatically synchronized to the cluster by ArgoCD.
What Can You Do With This?
- Deploy applications using Git-based workflows
- Auto-manage DNS records via External-DNS
- Auto-provision TLS certificates via cert-manager
- Load balance services on bare-metal via MetalLB
- Route HTTP traffic via NGINX Ingress
- Monitor cluster with Prometheus and Grafana
- Aggregate logs with Loki and Grafana Alloy
- Block ads network-wide with Pi-hole
- Manage service mesh traffic with Istio
- Enforce policies with OPA Gatekeeper
- Encrypt secrets with Sealed Secrets for GitOps workflows
Quick Links
- Components - What's running in the cluster
- Architecture - How it works under the hood
- Quick Start - Get up and running
- Deployment Flow - GitOps workflow explained
- Adding Apps - Deploy new applications
- Adding Nodes - Add worker nodes to cluster
- Troubleshooting - Common issues and solutions
Tech Stack
| Component | Purpose | Version |
|---|---|---|
| Kubernetes | Container orchestration | 1.29+ |
| ArgoCD | GitOps continuous delivery | Helm 9.4.10 |
| Helm | Package management | 3.x |
| MetalLB | Load balancer (bare-metal) | 0.14.8 |
| NGINX Ingress | HTTP routing | 4.11.3 |
| cert-manager | TLS certificates | 1.17.2 |
| External-DNS | DNS management | 1.15.0 |
| Cloudflare | DNS provider | - |
| Prometheus Stack | Monitoring & alerting | 68.0.0 |
| Loki | Log aggregation | 6.55.0 |
| Grafana Alloy | Observability collector | 0.10.0 |
| Istio | Service mesh | 1.24.0 |
| OPA Gatekeeper | Policy engine | 3.22.0 |
| Sealed Secrets | Secret encryption | 2.18.4 |
| Pi-hole | Network ad-blocking | Latest |
Prerequisites
- Kubernetes cluster (kubeadm, v1.29+)
- kubectl configured with cluster access
- GitHub personal access token (with repo access)
- Cloudflare account + API token (for DNS-01 challenges)
Key Features
- GitOps Workflow: All changes go through Git, ArgoCD automatically syncs
- Automated TLS: Let's Encrypt certificates with auto-renewal
- Auto DNS: Automatic DNS record creation via External-DNS
- Monitoring Stack: Prometheus + Grafana for metrics and alerting
- Logging: Loki + Grafana Alloy for log aggregation
- Network Ad-blocking: Pi-hole for network-wide ad and tracker blocking
- Service Mesh: Istio for traffic management, security, and observability
- Policy Engine: OPA Gatekeeper for admission control and audit
- Secret Management: Sealed Secrets for encrypted secrets in Git