160 lines
7.1 KiB
Markdown
160 lines
7.1 KiB
Markdown
# 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 |
|
|
|
|
다음 세 질문을 순서대로 사용합니다.
|
|
|
|
1. 누가 소비하고 장애 영향을 받는가?
|
|
2. 누가 변경을 승인하고 lifecycle을 책임지는가?
|
|
3. 다른 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입니다.
|
|
|
|
```text
|
|
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으로 옮깁니다.
|
|
|
|
```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는
|
|
`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도 같은 소유권 언어를 사용합니다.
|
|
|
|
```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 | `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에 먼저
|
|
기록합니다.
|