project-gitops/docs/adr/0007-repository-ownership-boundaries.md

ADR 0007: Repository ownership boundaries

Status: accepted

Date: 2026-07-26

Context

기존 layout은 Vault, PostgreSQL, Keycloak과 Project Auth 구성을 모두 platform 또는 foundation으로 표현했습니다. 이 이름은 설치 순서를 보여 주지만 누가 소비하고 변경을 책임지는지 구분하지 못했습니다. 클러스터별 최종 구성도 manifests라는 일반 이름 아래 섞여 있어 base와 overlay의 관계가 불명확했습니다.

이 저장소는 하나의 실제 사내 플랫폼을 배포하는 저장소가 아니라 Project Auth를 예제로 한 독립 GitOps reference lab입니다. 따라서 존재하지 않는 팀/환경을 가정한 추상화보다 현재 리소스의 실제 owner와 lifecycle을 명확히 해야 합니다.

Decision

최상위 Kubernetes desired state를 다음 소유권으로 분류합니다.

• platform: 여러 system이 사용할 수 있고 독립 lifecycle을 가진 cluster capability
• systems: 특정 bounded context가 소유하는 backing services와 domain configuration
• workloads: 별도 source repository와 release digest를 가진 first-party 실행 애플리케이션
• clusters/<cluster>/overlays: 위 base에 namespace, image, host, secret reference, network boundary를 결합한 최종 구성

Vault는 platform/shared-services/vault에 둡니다. Sealed Secrets와 Vault Agent Injector는 cluster addon inventory로 관리합니다. PostgreSQL, Keycloak, realm/client sync는 Project Auth 전용이므로 systems/auth-system으로 이동합니다. auth-server와 api-server는 workloads에 유지합니다.

Project Auth backing system의 namespace는 auth-system-dev로 정하고, Vault KV 경로도 systems/auth-system 또는 실제 workload owner를 반영하도록 바꿉니다.

foundation은 ownership directory로 사용하지 않습니다. 준비 순서는 분리된 ApplicationSet category, 명시적 autoSync gate, runbook과 workload retry/idempotency로 표현합니다.

Consequences

• 디렉터리 경로만 보고 owner와 blast radius를 추론할 수 있습니다.
• Base는 환경 중립 contract를 목표로 하고 Argo CD는 cluster overlay만 source로 사용합니다. 현재 Keycloak/Vault base의 dev-only 값은 알려진 후속 리팩터링 대상입니다.
• auth-system 이동은 namespace, DNS, NetworkPolicy, Vault policy/path와 Terraform role binding을 함께 바꾸는 migration입니다. 단순 파일 이동으로 취급하면 안 됩니다.
• ApplicationSet 도입은 반복 YAML을 줄이지만 각 파일에 project를 고정하고 Git 항목에는 component, cluster, destination, path와 quoted autoSync를 명시하도록 요구합니다. Git revision은 template의 main으로 고정합니다.
• 새 capability가 공용인지 system 전용인지 애매하면 소비자 수, owner, release cadence가 분리되는지를 먼저 검토합니다.
• 실제 production 요구가 생기기 전에는 production skeleton을 만들지 않습니다.

세부 path와 예시는 docs/architecture/repository-taxonomy.md를 따른다.