devops-infra-argo-config-gcp/claude/02-app-of-apps-pattern.md

Per AI Blitz Plan §6. Layer: 1-T.

02 — App-of-Applications Pattern

The chain

incubator/<env>/<cluster>.yaml          ← Parent Application (managed by ArgoCD on admin cluster)
    │
    │  source: this repo / generic-argo-apps-chart/
    │  valueFiles: ../values/<env>/<cluster>-values.yaml
    ▼
generic-argo-apps-chart/templates/genericTemplate.yaml
    │
    │  iterates appSpec[] array
    ▼
One child ArgoCD Application per appSpec entry
    │
    │  source: devops-infra-helm-charts / helm-templates/<chartDir>/
    │  valueFiles: helm-overrides/<cluster>/<valuesDir>/custom-values.yaml
    ▼
Deployed tool on target cluster (Contour, Kyverno, VictoriaMetrics, etc.)

How it works

1. Incubator Application lives on the admin cluster's ArgoCD. It points at generic-argo-apps-chart/ in this repo, using the cluster's values file.
2. Generic chart (genericTemplate.yaml) iterates over appSpec[] and renders one full ArgoCD Application manifest per entry.
3. Child Applications appear in ArgoCD, each pointing at a specific chart + override values in devops-infra-helm-charts.
4. Auto-sync is enabled — ArgoCD syncs child Applications immediately when the parent renders new manifests.

Adding a new tool

Add one entry to appSpec[] in the cluster's values file. The generic chart renders the Application on the next sync — no YAML boilerplate needed.

Key invariant (R2)

Each cluster requires exactly three things working together:

File	Location	Role
Incubator Application	incubator/<env>/<cluster>.yaml	Parent — scans values file
Values file	values/<env>/<cluster>-values.yaml	Tool list (appSpec[])
Generic chart	generic-argo-apps-chart/	Renderer — produces child Applications

Breaking any leg of this triangle breaks the cluster's entire tooling. See SANCTITY_RULES.md R2.