Reference

Important Files

File	Purpose
build/scripts/bootstrap.sh	Bootstrap cluster with ArgoCD and system apps
build/scripts/deploy.sh	Deploy apps using Git tags
build/scripts/prepare-release.sh	Create release with Git tag
charts/system-apps/templates/*.yaml	System app ArgoCD templates
cluster/*/config.yaml	Environment-specific settings
cluster/*/argocd-values.yaml	ArgoCD Helm values
config/*/applications/*-values.yaml	App-specific values
charts/argocd-project/values.yaml	ArgoCD AppProject definitions

Make Targets

# Bootstrap cluster
make bootstrap

# List environments
make list-envs

# List apps
make list-apps

# Render values (dry run)
make render-values ENV=dev

# Deploy specific app (local, bypass ArgoCD)
make deploy-app ENV=dev APP=namespace-manager

# Deploy all apps to environment (local)
make deploy-env ENV=dev

# Create release
make prepare-release REPO_ARGS="--repo owner/repo --message 'Release v1.0.0'"

# Deploy latest to environment
make deploy ENV=dev

# Dry run
make deploy-dry-run ENV=dev

Deploy Script Options

# Deploy latest tag
./build/scripts/deploy.sh -e dev

# Deploy specific version
./build/scripts/deploy.sh -e dev -v v1.0.0

# Dry run
./build/scripts/deploy.sh -e dev -d

# Force deploy
./build/scripts/deploy.sh -e dev -f

Environment Variables

Variable	Required	Description
GITHUB_TOKEN	Yes	GitHub personal access token for ArgoCD repo access
CLOUDFLARE_TOKEN	Yes	Cloudflare API token for DNS-01 challenges

Helm Template Conventions

• Use clusterEnv variable to reference correct values file
• Wrap wildcards (*) in quotes: namespace: '*'
• Templates must check apps.<appName>.enabled before rendering
• Always quote namespace/server values with | quote
• Use nindent for proper indentation in included templates

Adding a New Environment

Create cluster/<env>/config.yaml:

clusterEnv: <env>
clusterPath: cluster/<env>

repoURL: https://github.com/<org>/k8s-playground-cluster
targetRevision: main

argocd:
  version: "9.4.10"

apps:
  namespace-manager:
    enabled: true
    destinationNamespace: default
  cert-manager:
    enabled: true
    version: "1.17.2"
  # ... other apps

Create cluster/<env>/argocd-values.yaml for ArgoCD configuration.

Adding AppProject

Edit charts/argocd-project/values.yaml:

projects:
  - name: new-project
    enabled: true
    description: New project
    sourceRepos:
      - https://github.com/<org>/k8s-playground-cluster.git
    destinations:
      - namespace: '*'
        server: https://kubernetes.default.svc
    clusterResourceWhitelist:
      - group: '*'
        kind: '*'

Version Matrix

Component	Version	Namespace	Sync Wave
ArgoCD	9.4.10	argocd	-1
AppProject	N/A	argocd	-1
cert-manager	1.17.2	cert-manager	1
MetalLB	0.14.8	metallb-system	1
NGINX Ingress	4.11.3	ingress-nginx	1
External-DNS	1.15.0	external-dns	1
local-path-provisioner	v0.0.34	local-path-storage	0
kube-prometheus-stack	68.0.0	monitoring	3
Loki	6.55.0	monitoring	3
Grafana Alloy	0.10.0	monitoring	4
Istio	1.24.0	istio-system	2-3
OPA Gatekeeper	3.22.0	gatekeeper-system	5
Gatekeeper Policies	N/A	gatekeeper-system	6
Sealed Secrets	2.18.4	kube-system	7
cluster-configs	N/A	various	3
Pi-hole	Latest	pihole	8

URLs

Service	URL
ArgoCD	https://argo.ssdk8s.xyz
Prometheus	https://prometheus.ssdk8s.xyz
Grafana	https://grafana.ssdk8s.xyz
Alertmanager	https://alertmanager.ssdk8s.xyz

Default Credentials

Service	Username	Password Command
ArgoCD	admin	kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
Grafana	admin	kubectl get secret kube-prometheus-stack-grafana -n monitoring -o jsonpath='{.data.admin-password}' | base64 -d

Sync Wave Reference

Applications are deployed in order based on sync wave annotations:

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