# Deployment architecture

## Reconciliation boundaries

```text
Gitea main
  |
  +-- Argo CD root -> AppProjects + child Applications -> Kubernetes
  |
  +-- approved Terraform runner -> Vault API
```

Argo CD는 Kubernetes desired state만 관리합니다. 최초 Argo 설치/root
seed와 문서화된 recovery 외에는 직접 cluster mutation을 하지 않습니다.
Terraform은 Config Management Plugin이나 Argo hook 안에서 실행하지
않습니다.

## Kustomize ownership

- `platform/`, `workloads/`: 환경 중립 base
- `clusters/dev-k3s/manifests/`: namespace, host, image, Vault role 및
  NetworkPolicy를 포함하는 최종 cluster composition
- Argo CD Application: final composition만 source로 사용

지원하지 않는 production overlay는 존재하지 않습니다. production
계약과 승인 경계가 확정될 때 별도로 생성합니다.

## In-application ordering

`auth-server`의 한 sync operation 안에서:

- 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을 사용합니다.

## Stateful lifecycle

Vault와 PostgreSQL PVC는 `Prune=false`로 보호합니다. child Application
prune/delete는 확인이 필요합니다. path 이동이나 Application rename 전에는
새 owner가 동일 live resource를 정상적으로 추적하는지 확인한 후 이전
owner를 non-cascading 방식으로 제거합니다.

## Image promotion

첫-party image는 애플리케이션 CI가 얻은 정확한 GHCR digest를 Gitea
workflow에 전달합니다. workflow는 digest 변경 PR을 만들고, validation과
승인을 거쳐 merge된 뒤 Argo CD가 배포합니다.

현재 short-SHA tag는 migration 시점의 예외입니다. private GHCR을 읽을
자격증명이 이 저장소 실행 환경에 없으므로 임의 digest로 바꾸지 않았고,
다음 정상 promotion에서 `digest:`로 교체됩니다.