project-infra/k8s/base/app/AGENTS.md

k8s/base/app AGENTS

Role:

• own application-facing infrastructure base units
• define environment-neutral app workload, service, config reference, secret reference, storage, network policy, probe, and resource shapes
• organize many services by domain/service path directly under k8s/base/app/<domain>/

Current structure:

• domains sit directly under k8s/base/app/ (identity/, storage/, test/)
• inside each domain, separate by workload role (stateful/, stateless/)
• example: identity/auth/stateful/identity-postgres/, identity/auth/stateless/auth-server/

Allowed:

• Kustomize base edits for application units
• Deployment / StatefulSet / Job / CronJob base resources
• Service / NetworkPolicy / PDB / HPA base resources
• ConfigMap / Secret reference wiring without secret values
• probe / resource / PVC / StorageClass reference shape
• component-specific manifests aligned with standards

Forbidden:

• environment-specific values that belong in k8s/overlays/<env>
• editing packaged K3s component manifests directly
• treating server-local manifests as source of truth
• embedding production secret values in Git
• generating opaque YAML via script as the primary ownership path
• merging unrelated app rollout + migration + cluster upgrade into one hidden change

Read first:

• /docs/standards/infra/architecture-environments.md
• /docs/standards/infra/kustomize.md
• /docs/standards/infra/config-and-secrets.md
• /docs/standards/infra/workload-selection.md
• /docs/standards/infra/storage-pvc.md
• /docs/standards/infra/network-ingress-tls.md
• /docs/standards/infra/resources-probes-availability.md
• /docs/standards/infra/security-hardening.md
• /docs/standards/infra/observability-health.md
• /docs/standards/infra/db-and-migration.md

Component-specific routing:

• paths containing keycloak -> /docs/standards/infra/keycloak.md
• paths containing vault -> /docs/standards/infra/vault.md
• paths containing minio -> /docs/standards/infra/minio.md
• paths containing flyway or migration jobs -> /docs/standards/infra/flyway.md

Examples:

• /docs/examples/infra/kustomize.md
• /docs/examples/infra/config-and-secrets.md
• /docs/examples/infra/workload-selection.md
• /docs/examples/infra/storage-pvc.md
• /docs/examples/infra/network-ingress-tls.md
• /docs/examples/infra/resources-probes-availability.md
• /docs/examples/infra/security-hardening.md
• /docs/examples/infra/observability-health.md
• /docs/examples/infra/db-and-migration.md
• /docs/examples/infra/keycloak.md
• /docs/examples/infra/vault.md
• /docs/examples/infra/minio.md
• /docs/examples/infra/flyway.md

Rules:

• base must stay environment-neutral
• app services default to ClusterIP
• public exposure must be explicit and added through overlays/ingress policy
• health/metrics/admin endpoints stay non-public by default
• DB migration must stay separate from app startup
• stateful workloads must have explicit storage and restore reasoning
• domain/unit nesting should make ownership clear for large service counts