gitops AGENTS

Role:

own Kubernetes/K3s source-of-truth manifests and Kustomize composition
keep catalog bases, environment overlays, cluster entrypoints, and Vault Secrets Operator assets separate
make render / validate / diff / apply possible from Git without relying on live cluster state

Scope:

apps/: app-owned workload/data/operation catalogs
platform/: shared services and operator catalogs
policies/: security and governance catalogs
tenants/: namespace/RBAC/quota catalogs
clusters/<env>/<cluster>/namespaces and stages/: deployable environment composition
clusters/<env>/<cluster>/all/: render/audit aggregate only

Read first:

Rules:

prefer kubectl kustomize, kubectl diff -k, and kubectl apply -k
apply stage entrypoints only; never apply an environment all/ aggregate
do not use server-local manifests as source of truth
do not place environment differences in a catalog base/
do not place base resource definitions directly in overlays unless the resource is environment-only by design
do not commit production secret values
keep scripts as helpers; manifests remain declarative source

Catalog base contract:

shared labels, selectors, probes, resources, services, storage and policy shape are allowed
environment hostnames, cluster contexts, production-only sizing, rollout image references, deletion overrides and secret values are forbidden
every base must be reusable by lab, staging and prod overlays
ownership must remain visible in the catalog unit path