project-infra/gitops/clusters/AGENTS.md

gitops/clusters AGENTS

Role:

• own environment-specific Kustomize composition
• express only the differences between environments and reusable bases
• make environment-level render, diff, apply, audit, and GitOps sync straightforward

Scope:

• <environment>/<region-or-cluster>/stages/
• <environment>/<region-or-cluster>/all/

Allowed:

• namespace selection
• replicas
• resource requests/limits overrides
• image tags or image references
• ingress host/TLS differences
• environment-specific patches
• environment-specific secret references
• storage class and retention differences

Forbidden:

• copying full base manifests into overlays
• redefining base resources wholesale without a clear environment-only reason
• placing production secret values in Git
• changing service ownership or workload kind without updating the base and standards
• mixing multiple environments in one overlay

Read first:

• /docs/standards/infra/kustomize.md
• /docs/standards/infra/architecture-environments.md
• /docs/standards/infra/config-and-secrets.md
• /docs/standards/infra/network-ingress-tls.md
• /docs/standards/infra/resources-probes-availability.md
• /docs/standards/infra/security-hardening.md
• /docs/standards/infra/operations-runbook-upgrade-rollback.md

Rules:

• cluster entrypoints are environment-first by design
• stages/* are deployable entrypoints; all/ is validation-only
• controller readiness and one-shot completion belong between stage applies
• keep patches small and named by target and intent
• render and diff the target environment before apply
• prod overlays must be the most conservative environment
• if an overlay starts re-declaring most of a resource, move common shape back into its catalog base