project-infra/AGENTS.md

AGENTS.md

Read order:

1. /AGENTS.md
2. nearest nested AGENTS.md
3. /docs/standards/infra/STYLE.md (normative labels/naming/ports/images/resources — always read before any manifest work)
4. relevant /docs/standards/infra/**
5. relevant /docs/examples/infra/**
6. current request

WARNING TO AI AGENTS: You MUST READ the files in /docs/standards/infra/ and /docs/examples/infra/ using your file reading tools BEFORE proposing or writing any K8s manifests. DO NOT rely on generic Kubernetes knowledge. The standard documents contain mandatory strict rules (e.g., probe settings, security contexts, non-root constraints, resource limits, namespace strategies) that MUST be hardcoded into your output. Generating plain boilerplate YAML without strict standards compliance is a critical failure.

Repo role:

• this repository owns infrastructure lifecycle and Kubernetes/K3s desired state
• source of truth is Git + IaC under infrastructure/ + Kustomize under gitops/
• scripts are helper tools, not the source of truth
• runtime cluster state or server-local manifest files are not authoritative

Primary directories:

• bootstrap/: foundation and selected GitOps controller bootstrap
• infrastructure/components/: reusable IaC primitives
• infrastructure/stacks/: optional reusable compositions
• infrastructure/live/: the only IaC plan/apply and state entrypoints
• gitops/apps/: app-owned workloads, data, and one-shot operations
• gitops/platform/: shared services, operators, ingress, mesh, storage, and secret delivery
• gitops/policies/: reusable governance and security policy
• gitops/tenants/: namespace, RBAC, quota, and tenant boundaries
• gitops/clusters/<env>/<cluster>/namespaces and stages/: current deployable Kubernetes entrypoints
• gitops/clusters/<env>/<cluster>/all/: render/audit aggregate; never apply it
• scripts/: render, diff, apply, validate, backup, and restore helpers
• docs/standards/infra/: infra standards
• docs/examples/infra/: approved examples

Current runtime exception:

• lab has no Argo CD/Flux controller; scripts/bin/bootstrap.sh applies the cluster namespaces entrypoint and ordered stages/*; all/ remains audit-only

Structure principle:

• catalogs are organized by ownership; every unit may contain an environment-neutral base and focused overlays/<env>
• catalog directories are never deployment/controller roots
• infrastructure/live and gitops/clusters are environment-first entrypoint trees
• current lab rollout ownership lives under gitops/clusters/lab/main/namespaces and gitops/clusters/lab/main/stages
• _template is copied to start new units and is never imported by live/cluster roots
• approved manifest examples live only under docs/examples/infra

Hard bans:

• do not treat /var/lib/rancher/k3s/server/manifests as source of truth
• do not edit K3s packaged component manifests directly
• do not put production secrets in Git/plain manifests
• do not bypass Kustomize with ad-hoc generated YAML as the primary path
• do not mix app rollout, DB migration, and control-plane upgrade in one opaque step
• do not apply gitops/clusters/<env>/<cluster>/all; deploy ordered stage entrypoints
• do not expose health, metrics, admin, or management endpoints publicly by default
• do not use hostPath as an operating default
• do not use start-dev/dev-mode style configs for production components
• do not rely on default namespace for production workloads

Global routing:

• environment / namespace / source-of-truth / K3s packaged components -> /docs/standards/infra/architecture-environments.md
• config / secret / Vault delivery strategy -> /docs/standards/infra/config-and-secrets.md
• workload kind selection -> /docs/standards/infra/workload-selection.md
• storage / PVC / storage class / retention -> /docs/standards/infra/storage-pvc.md
• network / service / ingress / TLS -> /docs/standards/infra/network-ingress-tls.md
• resources / probes / quota / PDB / HPA -> /docs/standards/infra/resources-probes-availability.md
• backup / restore -> /docs/standards/infra/backup-restore.md
• security hardening / RBAC / network policy / pod security -> /docs/standards/infra/security-hardening.md
• operational procedure / upgrade / rollback -> /docs/standards/infra/operations-runbook-upgrade-rollback.md
• observability / health / metrics / logs -> /docs/standards/infra/observability-health.md
• database / PostgreSQL / migration ownership / Flyway flow -> /docs/standards/infra/db-and-migration.md
• K3s-only rules -> /docs/standards/infra/k3s-specific.md
• scripts structure and shell rules -> /docs/standards/infra/scripts.md
• Kustomize structure and overlay rules -> /docs/standards/infra/kustomize.md

Component routing:

• Keycloak -> /docs/standards/infra/keycloak.md
• Vault -> /docs/standards/infra/vault.md
• MinIO -> /docs/standards/infra/minio.md
• Flyway -> /docs/standards/infra/flyway.md

Before editing:

• identify target environment: lab / staging / prod
• identify target unit: app / data / platform / operation / script / docs
• identify whether the change belongs in bootstrap, infrastructure, a gitops catalog, gitops/clusters, scripts, or docs
• identify workload type: Deployment / StatefulSet / Job / CronJob
• identify whether storage, secret delivery, ingress, migration, or rollback path changes
• identify whether the change touches a K3s-specific rule

Default execution flow:

• read the owning standard first
• prefer changing IaC/Kustomize source under infrastructure/ or gitops/ over live state
• prefer render -> validate -> diff -> apply thinking
• prefer explicit rollback/restore path before risky changes

If the request touches multiple areas, use this priority:

1. k3s-specific.md
2. architecture-environments.md
3. db-and-migration.md
4. the directly relevant component standard
5. supporting standards such as storage / security / operations / observability