refactor(gitops): establish platform ownership boundaries

2026-07-26 01:34:29 +09:00
parent 293ee6fc97
commit a6f6c663e0
121 changed files with 2801 additions and 1204 deletions
@@ -0,0 +1,157 @@
+# Repository taxonomy
+
+이 문서는 새 리소스를 어느 디렉터리에 둘지 결정하는 기준입니다. 이
+저장소는 Project Auth를 예제로 삼는 독립 reference lab이며, 디렉터리
+이름은 조직의 중요도나 설치 순서가 아니라 소유권을 표현합니다.
+
+## 분류 기준
+
+| 분류 | 판단 질문 | 현재 예 |
+|---|---|---|
+| `platform` | GitOps control plane이거나, 둘 이상의 system이 독립 lifecycle로 소비할 cluster capability인가? | Argo inventory, Vault shared service |
+| `systems` | 하나의 bounded context가 함께 소유하는 backing system인가? | Project Auth의 PostgreSQL, Keycloak, realm/client sync |
+| `workloads` | 별도 source repository에서 빌드하는 first-party 실행 단위인가? | `auth-server`, `api-server` |
+| `clusters` | 특정 클러스터의 최종 composition 값인가? | namespace, host, digest, Vault role, NetworkPolicy |
+| `iac` | Kubernetes가 아닌 외부 API 객체를 선언하는가? | Vault mounts, policies, auth roles, database roles |
+| `bootstrap` | GitOps controller가 존재하기 전에 필요한 최소 seed인가? | Argo CD 설치 버전, 제한된 control-plane AppProject와 root Application |
+
+다음 세 질문을 순서대로 사용합니다.
+
+1. 누가 소비하고 장애 영향을 받는가?
+2. 누가 변경을 승인하고 lifecycle을 책임지는가?
+3. 다른 bounded context와 독립적으로 교체하거나 배포할 수 있는가?
+
+제품 이름만으로 분류하지 않습니다. 예를 들어 Keycloak이 여러 system의
+공용 identity service가 되고 별도 owner와 release cadence를 갖게 되면
+실행 서비스는 `platform/`으로 이동할 수 있습니다. 그래도 Project Auth
+realm/client 구성은 `systems/auth-system/`에 남습니다. 현재 Keycloak과
+PostgreSQL은 Project Auth 전용이므로 모두 system 소유입니다.
+
+## Path contract
+
+환경 중립 base와 cluster-specific overlay를 분리하는 것이 목표
+contract입니다.
+
+```text
+platform/shared-services/<name>/base
+systems/<system>/base
+workloads/<workload>/base
+
+clusters/<cluster>/overlays/platform/<name>
+clusters/<cluster>/overlays/systems/<system>
+clusters/<cluster>/overlays/workloads/<workload>
+
+platform/control-plane/argocd/projects
+platform/control-plane/argocd/application-sets
+```
+
+Base에는 재사용 가능한 workload 구조, Service, ServiceAccount와 기본
+configuration contract를 둡니다. Overlay에는 다음처럼 클러스터와 환경을
+알아야 하는 값을 둡니다.
+
+- namespace와 public/internal host
+- image reference; 정상 promotion의 목표는 immutable digest
+- Vault auth role과 KV path annotation
+- NetworkPolicy의 namespace/CIDR
+- dev-only resource profile와 TLS 차이
+
+Argo CD는 base를 직접 source로 사용하지 않고 반드시 최종 overlay를
+reconcile합니다.
+
+현재 first-party overlay의 짧은 commit tag는 이관 예외입니다. Registry를
+검증할 credential 없이 임의 digest로 바꾸지 않고 다음 정상 promotion
+PR에서 immutable digest로 전환합니다.
+
+### 현재 base의 알려진 예외
+
+Base 내부의 PostgreSQL·Keycloak 참조는 namespace를 포함하지 않은 짧은
+Service DNS를 사용하므로 overlay namespace에 재사용할 수 있습니다. 다만
+아직 다음 dev/single-node 가정은 남아 있습니다.
+
+- `systems/auth-system/base`의 Keycloak 실행 command가 `start-dev`입니다.
+- `platform/shared-services/vault/base/files/vault/vault.hcl`이
+  `tls_disable = 1`과 고정된 single-node `node_id`를 사용합니다.
+
+이는 숨겨진 환경 중립성이 아니라 명시적인 리팩터링 부채입니다. 두 번째
+환경이나 replica를 만들기 전에 dev 전용 command, TLS와 node identity를
+overlay 또는 입력 가능한 configuration으로 옮깁니다.
+
+```text
+base -> dev-k3s overlay -> ApplicationSet inventory -> generated Application
+     -> Argo CD -> Kubernetes
+```
+
+## Platform 안의 두 역할
+
+`platform` ownership에는 다음 두 종류가 있습니다.
+
+- Cluster addon: Kubernetes API를 확장하거나 admission/control-plane
+  기능을 제공하는 외부 chart. 현재 Sealed Secrets와 Vault Agent Injector가
+  해당합니다. Inventory는
+  `platform/control-plane/argocd/application-sets/platform-addons.yaml`에
+  둡니다.
+- Shared service: 일반 workload처럼 namespace에서 실행되지만 여러 system이
+  사용할 수 있는 capability. 현재 Vault가 해당합니다.
+
+외부 Helm chart를 복사해 base처럼 유지하지 않습니다. chart version과
+values는 Argo inventory에서 pin합니다. 저장소가 직접 소유하는 shared
+service manifest만 `platform/shared-services/`에 둡니다.
+
+`foundation`은 소유권 분류가 아닙니다. Bootstrap 때 먼저 필요하다는 뜻은
+분리된 ApplicationSet category, `autoSync` gate와 runbook 순서로
+표현합니다. 따라서 새로운 `foundation/` business directory를 만들지
+않습니다.
+
+## System와 workload의 경계
+
+`systems/auth-system`은 인증 bounded context가 함께 책임지는 데이터와
+identity backing services입니다.
+
+- PostgreSQL StatefulSet와 초기 database contract
+- Keycloak server와 Project Auth realm
+- Keycloak client synchronization
+
+`workloads/auth-server`와 `workloads/api-server`는 각각 별도 source
+repository와 release digest가 있는 애플리케이션입니다. Workload가
+auth-system을 사용하더라도 두 lifecycle을 합치지 않습니다.
+
+Dev namespace도 소유권을 드러냅니다.
+
+| 소유 단위 | Namespace |
+|---|---|
+| Vault shared service와 injector | `vault` |
+| Project Auth backing system | `auth-system-dev` |
+| Auth workload | `auth-dev` |
+| API workload | `api-dev` |
+
+## Vault path grammar
+
+KV path도 같은 소유권 언어를 사용합니다.
+
+```text
+kv/dev/systems/auth-system/postgres/superuser
+kv/dev/systems/auth-system/postgres/auth-server
+kv/dev/systems/auth-system/postgres/keycloak
+kv/dev/systems/auth-system/keycloak/bootstrap-admin
+kv/dev/workloads/auth-server/keycloak-client
+```
+
+Vault policy 파일에는 KV-v2 API path인 `kv/data/...`를 사용하고, CLI에는
+mount-relative path인 `kv/dev/...`를 사용합니다. 이전
+`kv/dev/platform/...` 경로는 legacy migration source일 뿐 새 desired
+state가 아닙니다.
+
+## 새 항목 배치 예
+
+| 변경 | 위치 |
+|---|---|
+| 또 다른 공용 admission controller | `platform/control-plane/argocd/application-sets/platform-addons.yaml` |
+| 공용 object storage service base | `platform/shared-services/object-storage/base` |
+| Project Auth 전용 Redis | `systems/auth-system/base` |
+| 새 first-party worker | `workloads/<worker>/base` |
+| dev worker digest/secret annotation | `clusters/dev-k3s/overlays/workloads/<worker>` |
+| Vault workload policy/role | `vault-workloads` Terraform state와 `policies/vault/` |
+| Vault auth backend | `vault-foundation` Terraform state |
+
+분류가 애매하면 설치 순서가 아니라 owner와 소비자 경계를 ADR에 먼저
+기록합니다.