project-gitops/docs/decisions/0005-repository-layout.md

ADR 0005: Cluster-first repository layout

Status: accepted

Updated: 2026-07-26

현재는 단일 dev-k3s와 소수 workload를 다루므로 GitOps configuration monorepo를 유지합니다. Application source repository와 deployment configuration repository는 분리합니다. 이 저장소 자체는 독립 reference lab이며 범용 platform product로 간주하지 않습니다.

• gitops/platform, gitops/apps/systems, gitops/apps/workloads: ownership별 base; 환경 중립은 목표 contract
• gitops/clusters/<cluster>: GitOps controller가 읽는 cluster root
• gitops/clusters/<cluster>/overlays: cluster-specific final composition
• gitops/platform/control-plane/argocd/projects: Argo 권한 경계
• gitops/platform/control-plane/argocd/application-sets: reconciliation inventory
• infrastructure: Kubernetes manifest와 분리된 external API IaC
• bootstrap: controller가 존재하기 전의 최소 seed

gitops/clusters가 배포 가능한 최종 상태를 소유합니다. Argo CD는 catalog base를 직접 source로 사용하지 않습니다. foundation은 directory taxonomy가 아니라 bootstrap ordering/stage이고, 구체적인 ownership 분류는 ADR 0007을 따릅니다.

현재 Keycloak base의 start-dev와 Vault base의 TLS-off/single-node identity는 이 contract를 위반하는 알려진 리팩터링 부채입니다. 다른 환경을 추가하기 전에 해당 값을 component overlay나 configuration input으로 분리합니다.

Production 접근권한, 소유 팀, Terraform backend 또는 release cadence가 실제로 갈라질 때 platform GitOps, workload GitOps, IaC repository 분리를 재검토합니다. 존재하지 않는 환경의 skeleton은 유지하지 않습니다.