118 lines
4.7 KiB
Markdown
118 lines
4.7 KiB
Markdown
# Deployment architecture
|
|
|
|
## Reconciliation boundaries
|
|
|
|
```text
|
|
Gitea main
|
|
|
|
|
+-- Argo CD root
|
|
| -> AppProjects + ApplicationSets
|
|
| -> generated Applications
|
|
| -> Kubernetes
|
|
|
|
|
+-- approved Terraform runner
|
|
-> one of three Vault states
|
|
-> Vault API
|
|
```
|
|
|
|
Argo CD는 Kubernetes desired state만 관리합니다. 최초 Argo 설치와
|
|
bootstrap 전용 AppProject/root seed, 문서화된 recovery 외에는 직접
|
|
cluster mutation을 하지 않습니다. Terraform은 Config Management
|
|
Plugin이나 Argo hook 안에서 실행하지 않습니다. GHCR은 image artifact
|
|
registry이며 desired state source가 아닙니다.
|
|
|
|
## Kubernetes ownership
|
|
|
|
| Layer | 역할 |
|
|
|---|---|
|
|
| `platform/control-plane/argocd` | AppProject와 ApplicationSet control plane |
|
|
| `platform/shared-services/*/base` | 환경 중립을 목표로 하는 공유 cluster service base |
|
|
| `systems/*/base` | 환경 중립을 목표로 하는 bounded-context backing system base |
|
|
| `workloads/*/base` | first-party 애플리케이션 base |
|
|
| `clusters/dev-k3s/overlays/*` | dev namespace, host, digest, Vault role/path, NetworkPolicy를 합친 최종 구성 |
|
|
|
|
현재 concrete ownership은 Vault가 platform shared service,
|
|
PostgreSQL/Keycloak이 `systems/auth-system`, 두 서버가 workload입니다.
|
|
Argo CD Application은 base가 아니라 최종 cluster overlay만 source로
|
|
사용합니다.
|
|
|
|
현재 Keycloak base의 `start-dev`와 Vault base의
|
|
TLS-off/single-node identity는 dev-specific 예외입니다. 내부 Service
|
|
참조는 짧은 DNS로 namespace 중립화했지만, 남은 값을 overlay로 추출하는
|
|
작업은 후속 리팩터링입니다.
|
|
|
|
지원하지 않는 production overlay는 존재하지 않습니다. Production trust,
|
|
approval, TLS, availability contract가 확정될 때 별도로 설계합니다.
|
|
|
|
## Bootstrap progression
|
|
|
|
```text
|
|
Argo root
|
|
-> Sealed Secrets + Vault autoSync
|
|
-> Vault init
|
|
-> vault-foundation
|
|
-> vault-workloads
|
|
-> runtime secret seed
|
|
-> Vault Agent Injector autoSync gate
|
|
-> auth-system autoSync gate
|
|
-> PostgreSQL Healthy
|
|
-> vault-database
|
|
-> Keycloak/client sync ready
|
|
-> auth-server autoSync gate
|
|
-> auth-server Healthy
|
|
-> api-server autoSync gate
|
|
```
|
|
|
|
이 순서는 Application sync wave로 강제하지 않습니다. 각 전환은 health와
|
|
plan/diff를 확인한 별도 PR입니다. Gate가 닫힌 동안에도 generated
|
|
Application은 OutOfSync diff를 보여 줍니다.
|
|
|
|
## In-application ordering
|
|
|
|
`auth-server`의 한 sync operation 안에서는 다음 ordering을 사용합니다.
|
|
|
|
- generated ConfigMap과 일반 리소스: wave `0`
|
|
- database migration Sync hook: wave `5`
|
|
- Deployment: wave `10`
|
|
- north-south route: wave `20`
|
|
|
|
`auth-system`의 Keycloak client sync도 idempotent Sync hook이며 deadline,
|
|
backoff, `BeforeHookCreation,HookSucceeded` cleanup을 사용합니다.
|
|
Application 간 준비 순서와 Application 내부 hook 순서를 혼동하지
|
|
않습니다.
|
|
|
|
## Stateful lifecycle
|
|
|
|
Vault PVC에는 `Prune=confirm,Delete=confirm`이 명시되어 있습니다.
|
|
PostgreSQL PVC는 StatefulSet `volumeClaimTemplates`가 생성하며 현재
|
|
manifest에 별도 Argo prune annotation이 없습니다. Namespace와 generated
|
|
Application 삭제 보호만 믿지 말고 PostgreSQL retention/backup을 직접
|
|
확인해야 합니다. Path, namespace, Application 이름을 이동할 때는 다음을
|
|
별도 migration으로 다룹니다.
|
|
|
|
1. 기존 live object와 owner를 inventory합니다.
|
|
2. 새 owner가 같은 object를 안전하게 추적할 수 있는지 render/diff로
|
|
확인합니다.
|
|
3. Stateful data backup과 rollback 지점을 확보합니다.
|
|
4. 기존 owner를 non-cascading 방식으로 제거한 뒤 새 owner를 연결합니다.
|
|
|
|
이번 리팩터링에서는 `platform` namespace의 auth-system을
|
|
`auth-system-dev`로 옮기는 live 작업을 실행하지 않았습니다.
|
|
|
|
## Image promotion과 GHCR
|
|
|
|
정상 promotion에서 first-party image CI는 검증한 정확한 GHCR digest를
|
|
Gitea workflow에 전달합니다. Workflow는 전용 branch와 digest 변경 PR을
|
|
만들고 validation과 승인을 거쳐 merge된 뒤 Argo CD가 배포합니다.
|
|
Renovate는 외부 chart, third-party image와 Terraform provider만 갱신하며
|
|
두 first-party GHCR package는 비활성화합니다. 따라서 동일 image field를
|
|
promotion workflow와 Renovate가 동시에 쓰지 않습니다.
|
|
|
|
Private GHCR pull credential만 SealedSecret으로 Git에 저장합니다. 평문
|
|
credential이나 registry token은 manifest, Actions log, Terraform state에
|
|
남기지 않습니다.
|
|
|
|
현재 short-SHA tag는 migration 시점의 예외입니다. Registry 검증 없이
|
|
임의 digest를 만들지 않고 다음 정상 promotion에서 immutable digest로
|
|
교체합니다.
|