K3s 기반 인증 플랫폼의 인프라 source-of-truth입니다. 범용 k8s-template의 lifecycle/ownership 스켈레톤을 적용하고, 기존 리소스를 IaC catalog와 Kubernetes desired-state catalog로 분리했습니다.

현재 실제 배포 환경은 폐기 가능한 단일 클러스터용 lab입니다. dev, staging, prod IaC root는 확장 위치만 예약되어 있으며 아직 실행 가능한 Terraform/OpenTofu 구성이 아닙니다.

Lifecycle

bootstrap/foundation
        |
        v
infrastructure/live
        |
        v
bootstrap/gitops
        |
        v
gitops/clusters ──> platform / policies / tenants / apps

bootstrap/foundation: remote state와 초기 identity 같은 선행 조건
infrastructure/live: 네트워크, IAM, DNS, load balancer와 클러스터 생성 root
bootstrap/gitops: 선택한 GitOps controller와 cluster root 연결
gitops/clusters: Kubernetes desired state의 실제 배포 entrypoint

현재는 Argo CD/Flux가 설치되어 있지 않으므로 bootstrap/gitops는 확장 계약만 제공합니다. 실제 lab 배포는 readiness 경계를 보존하는 scripts/bin/bootstrap.sh가 ordered stage를 server-side apply합니다.

Repository layout

Path	Responsibility
`bootstrap/`	foundation 및 GitOps controller bootstrap
`infrastructure/components/`	재사용 가능한 compute/database/networking/storage IaC 단위
`infrastructure/stacks/`	반복되는 component 조합
`infrastructure/live/<env>/<leaf>/`	실제 IaC plan/apply와 state 경계
`gitops/apps/`	auth-server, PostgreSQL, migration 같은 app 소유 배포 정의
`gitops/platform/`	Traefik, Vault, VSO, Keycloak, MinIO, registry와 operator
`gitops/policies/`	공통 보안·거버넌스 정책
`gitops/tenants/`	namespace, RBAC, quota 같은 tenant 경계
`gitops/clusters/lab/main/namespaces`, `stages/`	현재 실제 배포 entrypoint
`gitops/clusters/lab/main/all/`	전체 render/schema/policy 감사 전용; apply 금지
`scripts/`	staged bootstrap, teardown와 검증 도구
`tests/kustomize-entrypoints.txt`	검증할 Kustomize entrypoint inventory

_template 디렉터리는 새 component/root를 만들 때 복제하는 뼈대입니다. 이 저장소는 이미 실제 lab 구성이 조립된 프로젝트이므로 루트에 별도 examples/를 유지하지 않습니다. 현재 구현을 참고하고 새 단위는 각 책임 폴더의 _template에서 시작합니다.

예를 들어 새 환경과 app을 시작할 때 다음처럼 복제합니다.

mkdir -p infrastructure/live/dev
cp -R infrastructure/live/_template infrastructure/live/dev/cluster

mkdir -p gitops/clusters/dev
cp -R gitops/clusters/_template gitops/clusters/dev/main

cp -R gitops/apps/_template gitops/apps/example-api

복제 후 __REPLACE_ME_*__ 값을 교체하고, 실제 cluster root에서 필요한 catalog만 참조합니다.

Current architecture

Traefik -> oauth2-proxy -> auth-server -> PostgreSQL
                  \-> Keycloak
docker-registry -> MinIO

Vault KV-v2 -> Vault Secrets Operator -> Kubernetes Secret -> workload

Namespace mnt에는 PSS Restricted와 default-deny NetworkPolicy를 적용합니다.
K3s packaged Traefik manifest는 수정하지 않고 HelmChartConfig만 관리합니다.
Flyway와 Keycloak realm import는 versioned one-shot operation입니다.
lab의 PostgreSQL, Vault와 MinIO는 운영 HA/backup 설계가 아닙니다.

Deploy

export KUBE_CONTEXT_LAB='<expected-context>'
bash scripts/bin/bootstrap.sh lab

배포 순서는 다음과 같습니다.

namespaces
00-platform
10-vault
20-secrets
30-data
35-registry
40-operations
50-apps

gitops/clusters/lab/main/all은 직접 apply하지 않습니다. CRD establishment, Vault 초기화, Secret materialization과 migration 완료는 한 번의 Kustomize apply로 표현할 수 없습니다.

Validate

make doctor
make check

# CI와 같은 pinned toolchain을 사용한 full gate
mise install
VALIDATION_PROFILE=full make check

make check는 템플릿 구조/민감 파일/IaC 계약 검증과 프로젝트별 Kustomize/schema/policy/shell/docs 검증을 모두 실행합니다.

Extension rules

외부 load balancer, VPC와 DNS는 infrastructure/components에서 구현하고 infrastructure/live root가 조립합니다.
in-cluster ingress/LB controller, Istio 같은 service mesh는 gitops/platform/<unit>에 두고 cluster stage가 선택합니다.
sidecar는 workload 기본 계약이면 app base, 환경별 선택이면 해당 overlays/<env>에 patch/component로 구성합니다.
VSO와 secret delivery controller는 gitops/platform/secret-delivery, 실제 비밀값은 Vault에 둡니다.
규모가 커지면 live/<provider>/<account>/<region>/<env>/<stack>과 clusters/<env>/<region>/<cluster>로 깊이만 확장하고 ownership 경계는 유지합니다.

Secret incident boundary

vault-init-keys.json은 Git에서 제외되며 로컬 권한은 0600이어야 합니다. 과거 Git 이력에 포함된 값은 이미 노출된 것으로 간주해야 하므로 실제 Vault root token과 unseal/recovery material을 회전한 뒤, 협업자와 조율하여 원격 이력을 별도로 정리해야 합니다.

README.md

Project Infra