Repository taxonomy

이 문서는 새 리소스를 어느 디렉터리에 둘지 결정하는 기준입니다. 이 저장소는 Project Auth를 예제로 삼는 독립 reference lab이며, 디렉터리 이름은 조직의 중요도나 설치 순서가 아니라 소유권을 표현합니다.

분류 기준

분류	판단 질문	현재 예
`gitops/platform`	GitOps control plane이거나, 둘 이상의 system이 독립 lifecycle로 소비할 cluster capability인가?	Argo inventory, Vault shared service
`gitops/apps/systems`	하나의 bounded context가 함께 소유하는 backing system인가?	Project Auth의 PostgreSQL, Keycloak, realm/client sync
`gitops/apps/workloads`	별도 source repository에서 빌드하는 first-party 실행 단위인가?	`auth-server`, `api-server`
`gitops/clusters`	특정 클러스터의 최종 composition 값인가?	namespace, host, digest, Vault role, NetworkPolicy
`infrastructure`	Kubernetes가 아닌 외부 API 객체를 선언하는가?	Vault mounts, policies, auth roles, database roles
`bootstrap`	GitOps controller가 존재하기 전에 필요한 최소 seed인가?	Argo CD 설치 버전, 제한된 control-plane AppProject와 root Application

다음 세 질문을 순서대로 사용합니다.

누가 소비하고 장애 영향을 받는가?
누가 변경을 승인하고 lifecycle을 책임지는가?
다른 bounded context와 독립적으로 교체하거나 배포할 수 있는가?

제품 이름만으로 분류하지 않습니다. 예를 들어 Keycloak이 여러 system의 공용 identity service가 되고 별도 owner와 release cadence를 갖게 되면 실행 서비스는 gitops/platform/으로 이동할 수 있습니다. 그래도 Project Auth realm/client 구성은 gitops/apps/systems/auth-system/에 남습니다. 현재 Keycloak과 PostgreSQL은 Project Auth 전용이므로 모두 system 소유입니다.

Path contract

환경 중립 base와 cluster-specific overlay를 분리하는 것이 목표 contract입니다.

gitops/platform/shared-services/<name>/base
gitops/apps/systems/<system>/base
gitops/apps/workloads/<workload>/base

gitops/clusters/<cluster>/overlays/platform/<name>
gitops/clusters/<cluster>/overlays/systems/<system>
gitops/clusters/<cluster>/overlays/workloads/<workload>

gitops/platform/control-plane/argocd/projects
gitops/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 가정은 남아 있습니다.

gitops/apps/systems/auth-system/base의 Keycloak 실행 command가 start-dev입니다.
gitops/platform/shared-services/vault/base/files/vault/vault.hcl이 tls_disable = 1과 고정된 single-node node_id를 사용합니다.

이는 숨겨진 환경 중립성이 아니라 명시적인 리팩터링 부채입니다. 두 번째 환경이나 replica를 만들기 전에 dev 전용 command, TLS와 node identity를 overlay 또는 입력 가능한 configuration으로 옮깁니다.

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는 gitops/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만 gitops/platform/shared-services/에 둡니다.

foundation은 소유권 분류가 아닙니다. Bootstrap 때 먼저 필요하다는 뜻은 분리된 ApplicationSet category, autoSync gate와 runbook 순서로 표현합니다. 따라서 새로운 foundation/ business directory를 만들지 않습니다.

System와 workload의 경계

gitops/apps/systems/auth-system은 인증 bounded context가 함께 책임지는 데이터와 identity backing services입니다.

PostgreSQL StatefulSet와 초기 database contract
Keycloak server와 Project Auth realm
Keycloak client synchronization

gitops/apps/workloads/auth-server와 gitops/apps/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도 같은 소유권 언어를 사용합니다.

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	`gitops/platform/control-plane/argocd/application-sets/platform-addons.yaml`
공용 object storage service base	`gitops/platform/shared-services/object-storage/base`
Project Auth 전용 Redis	`gitops/apps/systems/auth-system/base`
새 first-party worker	`gitops/apps/workloads/<worker>/base`
dev worker digest/secret annotation	`gitops/clusters/dev-k3s/overlays/workloads/<worker>`
Vault workload policy/role	`infrastructure/live/dev-k3s/vault-workloads`와 그 아래 `policies/`
Vault auth backend	`vault-foundation` Terraform state

분류가 애매하면 설치 순서가 아니라 owner와 소비자 경계를 ADR에 먼저 기록합니다.

7.1 KiB Raw Permalink Blame History