init: 폴더구조 설계 및 인프라 설계

2026-07-24 14:31:53 +09:00
parent 34ad612281
commit f9c463f87a
1839 changed files with 323096 additions and 1 deletions
@@ -0,0 +1,105 @@
+# 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 Kubernetes/K3s infrastructure source
+- source of truth is Git + Kustomize directories under `k8s/`
+- scripts are helper tools, not the source of truth
+- runtime cluster state or server-local manifest files are not authoritative
+
+Primary directories:
+- `k8s/base/`: environment-neutral Kustomize bases
+- `k8s/base/app/`: application-facing workload units
+- `k8s/base/managing/`: management/operations units such as bootstrap, migration, backup, restore, and admin jobs
+- `k8s/base/plugins/`: platform/plugin-style base resources
+- `k8s/overlays/<env>/`: environment overlays such as `dev`, `staging`, and `prod`
+- `k8s/scripts/`: render, diff, apply, validate, backup, and restore helpers
+- `docs/standards/infra/`: infra standards
+- `docs/examples/infra/`: approved examples
+
+Structure principle:
+- `k8s/base` is organized by operational ownership and workload role, not by environment.
+- `k8s/overlays` is organized by environment first, so large fleets can be rendered, diffed, applied, and audited environment-by-environment.
+- This repo intentionally does not use the small-project “each service owns its own base and overlays” pattern as the primary layout.
+- Service ownership still exists under `k8s/base/app/<domain>/<workload>/**`; environment rollout ownership lives under `k8s/overlays/<env>`.
+
+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 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: dev / staging / prod
+- identify target unit: app / managing / plugin / script / docs
+- identify whether the change belongs in `k8s/base`, `k8s/overlays/<env>`, `k8s/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 Kustomize source under `k8s/` over live cluster 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