Architecture

High-Level Overview

Component Flow

Directory Structure

k8s-playground-cluster/
├── Makefile                          # Build/deploy automation
├── build/scripts/
│   ├── bootstrap.sh                  # Initial cluster setup
│   ├── deploy.sh                     # Tag-based deployment
│   └── prepare-release.sh            # Release management
├── charts/
│   ├── argocd-project/               # ArgoCD AppProject definitions
│   ├── gatekeeper-policies/          # OPA Gatekeeper policies
│   ├── namespace-manager/            # Sample user application
│   ├── pi-hole/                      # Pi-hole Helm chart
│   └── system-apps/                  # System app ArgoCD templates
├── cluster/
│   ├── dev/
│   │   ├── config.yaml               # Dev environment config
│   │   ├── argocd-values.yaml        # ArgoCD Helm values
│   │   └── application/              # Dev-specific application configs
│   └── qa/
│       └── config.yaml               # QA environment config
└── config/
    ├── dev/applications/             # Dev app-specific values files
    └── qa/applications/              # QA app-specific values files

Deployment Architecture

GitOps Flow

1. Developer commits changes to Git repository
2. ArgoCD detects changes (via polling or webhook)
3. ArgoCD renders Helm templates with environment values
4. ArgoCD applies manifests to Kubernetes cluster
5. Kubernetes schedules and runs workloads
6. System components (cert-manager, external-dns) react to new resources

Sync Waves

ArgoCD syncs applications in order using annotations:

Wave	Components	Description
-1	ArgoCD, AppProject	Self-managing, must exist first
0	local-path-provisioner, namespace-manager	Storage and namespace setup
1	cert-manager, MetalLB, NGINX Ingress, External-DNS	Core infrastructure and networking
2	istio-base	Istio CRDs (must be before istiod)
3	istiod, loki, kube-prometheus-stack, cluster-configs	Service mesh control plane, monitoring
4	grafana-alloy, promtail	Log collectors
5	gatekeeper	OPA Gatekeeper admission controller
6	gatekeeper-policies	OPA policies (ConstraintTemplates, Constraints)
7	sealed-secrets	Secret encryption for GitOps
8	User applications	Application workloads

Multi-Environment Support

This setup supports multiple environments (dev, qa):

cluster/dev/config.yaml     → clusterEnv: dev
cluster/qa/config.yaml      → clusterEnv: qa

Currently, the dev environment is fully configured with all components, while qa has a minimal setup with core infrastructure only.

The environment configuration includes:

• config.yaml with enabled/disabled apps and versions
• App-specific values in config/dev/applications/
• ArgoCD sync and deployment configuration

Component Details

Core Infrastructure

Component	Purpose	Namespace
ArgoCD	GitOps controller	argocd
cert-manager	TLS certificate automation	cert-manager
MetalLB	LoadBalancer provider	metallb-system

Networking

Component	Purpose	Namespace
NGINX Ingress	HTTP/HTTPS routing	ingress-nginx
External-DNS	DNS record automation	external-dns

Storage

Component	Purpose	Namespace
local-path-provisioner	Dynamic PVC provisioning	local-path-storage

Observability

Component	Purpose	Namespace
kube-prometheus-stack	Metrics and alerting	monitoring
Loki	Log aggregation	monitoring
Grafana Alloy	Unified observability collector	monitoring

Service Mesh & Security

Component	Purpose	Namespace
Istio	Service mesh (traffic, security, observability)	istio-system
OPA Gatekeeper	Policy engine (admission control, audit)	gatekeeper-system
Sealed Secrets	Secret encryption for GitOps	kube-system
cluster-configs	Cluster-wide ConfigMaps and tuning	various

Applications

Component	Purpose	Namespace
Pi-hole	Network ad-blocking	pihole
namespace-manager	Sample user application	default

Network Flow

Security Boundaries

• Network Policies: Calico provides pod-to-pod network segmentation
• TLS: All ingress traffic encrypted via cert-manager + Let's Encrypt
• RBAC: Kubernetes role-based access control for all components
• GitOps: All changes audited via Git history