120 lines
5.9 KiB
Markdown
120 lines
5.9 KiB
Markdown
# 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
|