project-gitops/docs/decisions/0008-adopt-k8s-template-lifecycle-layout.md

ADR 0008: Adopt the Kubernetes template lifecycle layout

Status: accepted

Date: 2026-07-26

Context

기존 저장소는 clusters, platform, systems, workloads, iac/terraform, policies와 hack을 각각 최상위에 두었습니다. 리소스 소유권은 구분했지만 bootstrap, infrastructure, GitOps desired state의 수명주기 경계가 저장소 최상위에서 일관되게 드러나지 않았습니다.

Decision

k8s-template의 수명주기 구조를 canonical repository layout으로 채택합니다.

• Argo CD 최초 seed는 bootstrap/gitops/argocd에 둡니다.
• Vault Terraform component와 실행 root는 각각 infrastructure/components와 infrastructure/live에 둡니다.
• Kubernetes desired state는 gitops/platform, gitops/apps, gitops/clusters 아래에만 둡니다.
• 기존 system/workload 소유권 분류는 gitops/apps/systems와 gitops/apps/workloads 하위에서 유지합니다.
• 환경별 Vault ACL은 이를 소비하는 infrastructure/live state root의 policies에 함께 둡니다. Kubernetes admission 정책용 gitops/policies와 혼합하지 않습니다.
• gitops/clusters/dev-k3s를 Argo CD bootstrap root의 유일한 source로 사용하고, 이 root가 permission-scoped ApplicationSet control plane을 조립합니다.
• 공통 _template, 예제, 구조/보안 검증을 유지하고 프로젝트별 검증을 그 위에 추가합니다.

Consequences

• 최상위 경로만으로 bootstrap, infrastructure, GitOps lifecycle을 구분할 수 있습니다.
• 기존 AppProject, ApplicationSet, autoSync gate와 세 Vault state의 소유권은 유지됩니다.
• backend 예시는 각 live root에, Vault ACL은 소비 state에 가까이 위치합니다.
• Argo CD source path와 Terraform module source가 변경되므로 이미 연결된 live 시스템의 이관은 별도 diff, orphan/prune 검토와 승인 없이 실행하지 않습니다.
• 이 ADR의 구현은 Git 작업 트리에서만 수행하며 live cluster, Vault, Terraform backend를 변경하지 않습니다.