4.7 KiB
Sanctity Rules — devops-infra-argo-config
Non-negotiable rules for this repository. Violations are hard stops — not warnings, not suggestions.
Audience: Every agent and human who opens a PR against this repo.
Enforcement: Pre-commit hooks (TruffleHog, CAC validate, Yaak) + branch protection on
main. A merge tomainimmediately deploys — infra apps are auto-sync.
R1: main is production
A merge to main triggers immediate ArgoCD auto-sync across all managed clusters. There is no staging gate between merge and deploy.
- No experiments on
main. - No force-pushes to
main. - Every PR must pass pre-commit hooks and receive platform-team review before merge.
R2: The incubator ↔ values ↔ generic-chart contract is sacred
Each cluster is bootstrapped by exactly three things working together:
- Incubator file (
incubator/<env>/<cluster>.yaml) — parent ArgoCD Application that points at the generic chart + the cluster's values file. - Values file (
values/<env>/<cluster>-values.yaml) — definesclusterSpec,teamSpec,argocdSpec, and theappSpec[]list. - Generic chart (
generic-argo-apps-chart/) — renders one child ArgoCD Application perappSpecentry.
Breaking any leg of this triangle breaks the cluster's tooling. The naming conventions in CLAUDE.md are load-bearing — they are identifiers, not cosmetic.
R3: appSpec entries must reference existing chart and values in devops-infra-helm-charts
Every appSpec[].chartDir must correspond to a directory under devops-infra-helm-charts/helm-templates/. Every appSpec[].valuesDir must correspond to a directory under devops-infra-helm-charts/helm-overrides/<cluster>/. If either doesn't exist, the ArgoCD Application will fail to render.
Verify before adding:
# chartDir exists?
ls devops-infra-helm-charts/helm-templates/<chartDir>/
# valuesDir exists?
ls devops-infra-helm-charts/helm-overrides/<cluster>/<valuesDir>/custom-values.yaml
R4: Child Application names are auto-generated — do not invent names
The generic chart template generates Application names as:
<appSpec.name>-<mungedCluster>-<env>
Where cluster munging strips: k8s-, prd-, int-, dev-, -ase1; maps -ase1c to -c.
Example: keda on k8s-central-prd-ase1 becomes keda-central-prd.
Only use nameOverride when:
- The auto-generated name would exceed 253 characters (Kubernetes limit).
- There is a genuine name collision between two appSpec entries.
R5: repository.yaml is automation-owned
Owned by registry-bootstrap. Direct edits will be overwritten. To change ownership metadata, go to the upstream automation.
R6: Secrets stay out of git
No credentials, tokens, API keys, or passwords in any YAML file. The TruffleHog pre-commit hook will block the commit. If a secret is accidentally committed, it must be force-purged from history — this requires platform-team involvement.
R7: nameOverride is exceptional, not routine
Most PRs should not include nameOverride. When reviewing, flag any nameOverride that lacks a comment explaining why the auto-generated name was insufficient.
R8: One incubator file per cluster, one values file per cluster
The 1:1 mapping between incubator files and values files is structural. Do not create multiple incubator files for the same cluster or share a values file across clusters.
R9: Cluster folder/file names are routing keys
The cluster name in the values file (clusterSpec.destination.name) must match the incubator file name and the helm-overrides/ folder name in the sister repo. These names are used by ArgoCD for cluster routing — a mismatch means tools deploy to the wrong cluster or fail silently.
R10: Pre-commit hooks must pass
Run pre-commit run --all-files before pushing. Never use --no-verify to skip hooks. If a hook fails, fix the root cause.
The hooks are: TruffleHog (secrets scan), CAC validate (config validation), Yaak (additional linting).
R11: Branch protection trumps everything
All changes go via PR with required review. Direct pushes to main are blocked at the GitHub org level. No exceptions for "quick fixes" — the blast radius of a bad merge is immediate cluster-wide impact.
R12: AppProject wildcards are dangerous
The sre and sec projects currently allow * for source repos and destinations. Widening or modifying AppProject scope requires auditing every Application that references the project. A misconfigured project could allow unauthorized deployments.
How to cite these rules
In PR reviews or agent halt messages, cite as: "Blocked by R3 (SANCTITY_RULES.md) — chartDir must exist in devops-infra-helm-charts before adding appSpec."