refactor: Readme 수정 및 불필요한 문서 정리

This commit is contained in:
DongHyeonka
2026-10-02 18:22:57 +09:00
parent b8626946b1
commit e4a7f2a5ab
30 changed files with 214 additions and 6527 deletions
+211 -128
View File
@@ -1,162 +1,245 @@
# Project GitOps reference lab
# project-gitops
Project Auth를 예제로 사용해 작은 팀의 GitOps 운영 경계를 학습하고 검증하는
독립 reference lab입니다. 범용 사내 플랫폼이나 애플리케이션 소스
monorepo가 아닙니다. 현재 지원 대상은 단일 `dev-k3s` 클러스터뿐입니다.
Project Auth를 개발용 Kubernetes 클러스터 `dev-k3s`에 배포하는 GitOps 저장소다. `auth-server`, `api-server`와 이를 받치는 Keycloak, PostgreSQL, Vault의 배포 선언과 Vault 설정을 여기서 관리한다.
배포 기준 저장소는 내부 Gitea 한 곳입니다.
애플리케이션 소스와 이미지 빌드는 각 애플리케이션 저장소가 맡는다. 이 저장소에는 Kubernetes manifest, Argo CD 설정, Vault를 설정하는 Terraform 코드와 운영 절차만 둔다.
배포 기준 저장소는 내부 Gitea의 [donghyeon.kang/project-gitops](https://git.learn.hyeonworks.com/donghyeon.kang/project-gitops)다. Argo CD는 이 저장소의 `main` 브랜치를 배포 기준으로 삼고, 검증과 이미지 반영 workflow는 Gitea Actions에서 실행된다.
> **현재 상태**
>
> 2026-07-26에 저장소 구조와 리소스 소유권을 크게 바꿨다. 이 변경은 Git에서만 검증했고 실제 클러스터에는 아직 반영하지 않았다. 이미 떠 있는 리소스를 새 구조로 옮기는 작업은 manifest 수정이 아니라 별도 migration으로 다룬다.
## 구성
| namespace | 올라가는 것 | Argo CD Application | 초기 autoSync |
|---|---|---|---|
| `kube-system` | Sealed Secrets controller | `sealed-secrets-dev-k3s` | 켜짐 |
| `vault` | Vault 1대 (integrated Raft) | `vault-dev-k3s` | 켜짐 |
| `vault` | Vault Agent Injector | `vault-agent-injector-dev-k3s` | 꺼짐 |
| `auth-system-dev` | PostgreSQL, Keycloak, Keycloak client 동기화 Job | `auth-system-dev-k3s` | 꺼짐 |
| `auth-dev` | `auth-server`, DB migration Job | `auth-server-dev-k3s` | 꺼짐 |
| `api-dev` | `api-server` | `api-server-dev-k3s` | 꺼짐 |
서비스끼리는 이렇게 연결된다.
- `auth-server`는 Keycloak 로그인(OAuth2)을 처리하고 자체 JWT를 발급한다.
- JWT 서명에는 Vault Transit 키 `project-auth-jwt`를 쓴다. 서명용 개인키는 Vault 밖으로 나오지 않는다.
- `api-server`는 `auth-server`가 발급한 JWT를 검증만 한다. `api-server`에는 Vault role을 주지 않았다.
- 외부 요청은 `kube-system`의 Traefik ingress로 들어온다. dev host는 `auth-public.auth-dev.svc.cluster.local`, `api-public.api-dev.svc.cluster.local`, `keycloak-public.auth-system-dev.svc.cluster.local`이고 HTTP만 쓴다.
## 배포 흐름
Kubernetes 리소스와 Vault 설정은 서로 다른 경로로 반영한다.
```text
https://git.learn.hyeonworks.com/donghyeon.kang/project-gitops
Kubernetes 리소스
애플리케이션 저장소 CI ─▶ GHCR 이미지 ─▶ 이미지 변경 PR ─▶ CI 검증 ─▶ main ─▶ Argo CD ─▶ dev-k3s
(Argo CD는 autoSync가 켜진 Application만 자동 반영한다)
Vault 설정
Terraform 변경 PR ─▶ CI 검증 ─▶ 운영자가 plan 저장·검토 ─▶ 저장한 plan apply ─▶ Vault API
```
`auth-server`와 `api-server`의 소스 저장소는 이미지를 빌드해 GHCR에
올립니다. 정상 promotion 계약은 검증된 immutable digest를 바꾸는 PR입니다.
현재 overlay에는 이관 전의 짧은 commit tag가 남아 있으며, registry를
검증할 credential 없이 임의 digest로 바꾸지 않았습니다. 다음 정상
promotion workflow가 digest로 전환합니다.
- CI 검증은 PR과 `main` push마다 Gitea Actions가 `make check`를 실행하는 단계다([validate.yaml](.gitea/workflows/validate.yaml)).
- Argo CD 안에서 Terraform을 실행하지 않고, CI가 kubectl apply로 클러스터를 직접 바꾸지도 않는다. 같은 리소스를 두 도구가 함께 관리하면 서로의 변경을 되돌리고, Argo CD가 Terraform까지 맡으면 Vault 관리자 권한과 state lock까지 떠안게 되기 때문이다.
Kubernetes desired state는 Argo CD가, Vault API 객체는 Terraform이 각각
관리합니다. KV secret 값은 어느 쪽에도 저장하지 않습니다.
### 이미지 반영
## 지원 범위
이미지는 각 애플리케이션 저장소에서 빌드해 GHCR(`ghcr.io/donghyeonka/project-auth-server`, `ghcr.io/donghyeonka/project-api-server`)에 올린다. 배포할 이미지가 정해지면 Gitea Actions의 `Promote Dev Image by Pull Request` workflow([promote-image.yaml](.gitea/workflows/promote-image.yaml))를 수동 실행한다.
| 대상 | 상태 |
|---|---|
| `dev-k3s` | 지원하는 단일 노드 개발 환경 |
| production | 설계되지 않았으며 overlay/Application이 없음 |
| Istio | 보류; 향후 ambient mode 도입 조건만 기록 |
- 입력: 대상 서비스(`auth-server` 또는 `api-server`)와 `sha256:`으로 시작하는 이미지 digest
- 동작: `gitops/clusters/dev-k3s/overlays/workloads/` 아래 해당 서비스의 `kustomization.yaml` 이미지를 digest로 바꾼 브랜치를 만들고 PR을 연다. `main`에는 직접 push하지 않는다.
현재 Vault, PostgreSQL, ingress는 TLS가 없는 개발 프로파일이며 single-node
failure domain을 공유합니다. production 용도로 사용할 수 없습니다.
지금 overlay에는 이전 방식의 짧은 commit tag(`auth-server`는 `1f47f2c`, `api-server`는 `fd097c9`)가 남아 있다. registry에서 digest를 확인할 credential이 없어 임의로 바꾸지 않았고, 다음 promotion 때 digest로 바뀐다. 그때까지 검증 스크립트는 digest 또는 commit 형태의 tag만 허용한다.
2026-07-26의 repository/ownership 리팩터링은 Git 작업 트리에만 설계하고
검증했습니다. 실제 클러스터에는 적용하지 않았으며, 기존 리소스의 소유권
이관은 관련 runbook과 별도 승인 없이 실행하면 안 됩니다.
## 저장소 구조
## 제어 흐름
```text
application CI -> GHCR digest -> GitOps PR -> validation -> main
|
v
Argo CD ApplicationSet
|
v
Kubernetes
IaC PR -> Terraform plan -> approval -> one Vault state apply -> Vault API
```
Argo CD 최초 설치 뒤 bootstrap 전용 `gitops-control-plane` AppProject와
단일 root Application만 순서대로 직접 적용합니다. 이후 routine deployment는
Git 변경으로만 수행합니다. Terraform은 Argo CD hook이나 Config Management
Plugin 안에서 실행하지 않습니다.
## 저장소 분류
디렉터리는 제품 이름이 아니라 수명주기와 관리 책임을 기준으로 나눴다.
```text
bootstrap/
foundation/ 외부 state/identity 선행 조건 문서
gitops/argocd/ controller 버전, 제한된 AppProject와 단일 root seed
foundation/ Terraform backend, 최초 CI identity 같은 선행 조건 (문서만 있음)
gitops/argocd/ Argo CD 버전, bootstrap용 AppProject, root Application
gitops/
clusters/dev-k3s/ root Application이 읽는 진입점과 dev-k3s 전용 overlay
platform/ Argo CD AppProject·ApplicationSet, 공용 서비스(Vault) base
apps/systems/ Project Auth 전용 backing service(PostgreSQL, Keycloak) base
apps/workloads/ 별도 저장소에서 빌드하는 애플리케이션(auth-server, api-server) base
infrastructure/
components/ 재사용 Vault Terraform component
live/dev-k3s/
vault-foundation/ mount/auth와 delegated automation policy
vault-workloads/ workload ACL, auth role와 Transit key
vault-database/ PostgreSQL connection과 dynamic role
gitops/clusters/dev-k3s/
kustomization.yaml Argo CD가 읽는 유일한 cluster root
overlays/
platform/ 공유 서비스의 dev-k3s 최종 구성
systems/ bounded-context system의 dev-k3s 최종 구성
workloads/ first-party workload의 dev-k3s 최종 구성
gitops/platform/
control-plane/argocd/ AppProject와 ApplicationSet inventory
shared-services/ 여러 system이 쓰는 cluster capability base
gitops/apps/
systems/ bounded-context backing system base
workloads/ 별도 source repository를 가진 application base
scripts/ bootstrap, validation, dev Vault init entrypoint
docs/ architecture, ADR, guide와 runbook
examples/, tests/ 템플릿 예제와 저장소 수준 검증 영역
components/ 재사용 Terraform 모듈 (Vault policy 묶음, Kubernetes auth role)
live/dev-k3s/ Vault Terraform root 3개: vault-foundation, vault-workloads, vault-database
scripts/ bootstrap, 검증, dev Vault 초기화 스크립트
docs/runbooks/ 운영 절차
examples/ 구조 예제 (배포 대상 아님)
tests/ 저장소 수준 테스트 계획
```
각 catalog의 `_template`은 새 component를 만들 때 사용하는 복사 원본이며
Argo CD가 직접 reconcile하지 않습니다.
`gitops/` 안은 누가 쓰는지로 나눈다. 여러 서비스가 함께 쓰는 것은 `platform`, Project Auth 안에서만 쓰는 backing service는 `systems`, 별도 저장소에서 빌드하는 애플리케이션은 `workloads`다. 예를 들어 Keycloak은 지금 Project Auth만 쓰므로 `gitops/apps/systems/auth-system/`에 있다. 여러 서비스가 Keycloak을 공유하고 관리 주체가 갈라지면 `platform`으로 옮긴다.
분류는 제품 종류가 아니라 소비자, 소유자, 변경 주기로 결정합니다.
Vault는 공유 capability이므로 `gitops/platform/`, Project Auth 전용
PostgreSQL과 Keycloak은 `gitops/apps/systems/auth-system/`, 직접 빌드하는
서버는 `gitops/apps/workloads/`에 속합니다. namespace, host, image digest,
Vault role, NetworkPolicy 같은 클러스터별 값은
`gitops/clusters/dev-k3s/overlays/`에서 완결합니다. Vault ACL은 소비하는
Terraform state의 `policies/`에 함께 둡니다.
`_template/` 디렉터리는 새 항목을 만들 때 복사하는 원본이며 Argo CD 배포 대상이 아니다. `gitops/policies/`, `gitops/tenants/`, `infrastructure/stacks/`에는 아직 `_template/`만 있다.
자세한 판단 기준은
[repository taxonomy](docs/architecture/repository-taxonomy.md)와
[ADR 0007](docs/decisions/0007-repository-ownership-boundaries.md)을 따릅니다.
### base와 overlay
## Argo CD 단계 gate
`base/`에는 환경과 무관한 설정을 두고, dev-k3s에서만 쓰는 값(namespace, host, image, Vault annotation, NetworkPolicy)은 `gitops/clusters/dev-k3s/overlays/`에 둔다. Argo CD는 base를 직접 배포하지 않고 이 overlay를 읽는다.
Root Application은 `gitops/clusters/dev-k3s`만 source로 사용합니다. 이
cluster root가 `gitops/platform/control-plane/argocd`의 AppProject와
ApplicationSet을 조립하고, 각 ApplicationSet이 cluster overlay를
reconcile합니다. 각 inventory 항목은 `autoSync`를 quoted string으로
명시해야 합니다. 새 항목이나 외부 준비 조건이 있는 항목은
`autoSync: "false"`로 시작하고, 선행 controller, Vault 구성, runtime
secret, database 준비를 확인한 PR에서만 `autoSync: "true"`로 바꿉니다.
아직 base에 남은 dev 전용 설정이 있다. Keycloak의 `start-dev`, Vault의 TLS 비활성화와 고정 `node_id`다. 두 번째 클러스터를 만들 때는 이 값부터 overlay로 옮겨야 한다. Vault NetworkPolicy의 Kubernetes API CIDR와 node 주소는 overlay에 있지만 dev-k3s 값이므로 다른 클러스터에 그대로 복사하지 않는다.
Control-plane sync wave는 AppProject(`-10`)를 ApplicationSet(`-5`)보다
먼저 생성할 뿐, generated Application의 readiness를 보장하지 않습니다.
`autoSync` gate와 workload의 retry/idempotency가 실제 단계 전환을
담당합니다.
### 새 항목을 둘 위치
## Terraform state
| 추가할 것 | 위치 |
|---|---|
| admission controller 같은 cluster addon | `gitops/platform/control-plane/argocd/application-sets/platform-addons.yaml` |
| 여러 서비스가 함께 쓰는 서비스 | `gitops/platform/shared-services/서비스명/base` |
| Project Auth 전용 backing service | `gitops/apps/systems/auth-system/base` |
| 직접 빌드하는 애플리케이션 | `gitops/apps/workloads/서비스명/base` |
| dev 환경의 namespace, host, image, Vault 설정 | `gitops/clusters/dev-k3s/overlays/` |
| 새 Argo CD Application | 권한이 맞는 ApplicationSet의 element (`autoSync: "false"`로 시작) |
| Vault workload policy, Kubernetes auth role, Transit 키 | `infrastructure/live/dev-k3s/vault-workloads` |
| Vault의 PostgreSQL 연결, dynamic DB role | `infrastructure/live/dev-k3s/vault-database` |
| Vault mount, auth backend, 자동화용 위임 policy | `infrastructure/live/dev-k3s/vault-foundation` |
| Root | 소유 범위 | routine 실행 권한 |
|---|---|---|
| `vault-foundation` | mounts, auth backends/config, delegated automation policy와 선택적 CI JWT roles | 없음; bootstrap 또는 보안 관리자 승인 실행 |
| `vault-workloads` | workload ACL, Kubernetes auth role, 애플리케이션 Transit key | workload 전용 short-lived identity |
| `vault-database` | PostgreSQL connection과 `auth-db-migration-dev` dynamic role | database 전용 short-lived identity |
위치에 파일을 추가하는 것만으로 끝나지 않는 경우가 있다.
중요한 규칙은 다음과 같습니다.
- 새 namespace나 새 chart 저장소를 쓰면 해당 AppProject(`gitops/platform/control-plane/argocd/projects/`)의 `destinations`, `sourceRepos`도 고친다.
- 새 Vault workload policy나 role을 만들면 그 정확한 경로를 `vault-foundation`의 위임 policy(`policies/vault-workloads-automation-dev.hcl`)에 추가하고 `vault-foundation`을 다시 적용해야 한다. 위임 policy에는 wildcard를 쓸 수 없다.
- ApplicationSet element를 추가하거나 `autoSync` 값을 바꾸면 `scripts/project-validate.sh`의 개수 검사(현재 켜짐 2개, 꺼짐 4개)도 함께 고친다.
- Vault API 객체 하나는 정확히 한 state만 소유합니다.
- Delegated state는 자신에게 권한을 부여하는 policy/login role을 만들지
않습니다. 그것은 `vault-foundation`이 소유합니다.
- State 사이에 `terraform_remote_state`를 사용하지 않습니다.
- KV payload, Vault init JSON, token, PostgreSQL password를 Git이나
Terraform state에 저장하지 않습니다.
- Backend는 encryption, versioning, access control, locking을 제공해야
합니다.
## Argo CD
## 주요 명령
평소 변경은 Git PR로만 한다. 클러스터에 직접 적용하는 것은 최초 bootstrap과 runbook에 적힌 복구·해체 절차뿐이다.
bootstrap은 대상 클러스터의 context 이름을 확인한 뒤, 그 이름을 직접 적어 실행한다. 아래의 `dev-k3s`는 예시이므로 첫 명령에서 확인한 실제 context 이름으로 바꾼다.
```bash
make validate
make bootstrap KUBE_CONTEXT=<expected-context>
make terraform-plan \
TF_ROOT=vault-foundation \
BACKEND_CONFIG=.local/terraform-backend/dev-k3s/vault-foundation.s3.hcl
kubectl config get-contexts
make bootstrap KUBE_CONTEXT=dev-k3s
```
`terraform-apply`는 동일 입력과
`APPROVE_APPLY=dev-k3s/<root>`가 모두 있어야 실행되며 `auto-approve`를
사용하지 않습니다. 실제 bootstrap과 state 이동은 먼저 runbook의 중단
조건을 확인합니다.
`make bootstrap`은 `KUBE_CONTEXT` 값이 현재 kubectl context와 다르면 멈춘다. 이름을 직접 적어야 이 확인이 의미가 있다. `$(kubectl config current-context)`처럼 현재 값을 그대로 넘기면 항상 통과하므로 잘못된 클러스터를 막지 못한다. 실행하면 Argo CD `v3.4.2`를 설치하고(설치 manifest는 SHA-256으로 확인), bootstrap 전용 AppProject `gitops-control-plane`과 root Application `project-gitops-control-plane`을 적용한다.
## 문서
```text
root Application (project-gitops-control-plane)
└─ gitops/clusters/dev-k3s
└─ gitops/platform/control-plane/argocd
├─ AppProject 4개: platform-addons, platform-services, systems, workloads
└─ ApplicationSet 4개 ─▶ Application 6개
```
- [Repository taxonomy](docs/architecture/repository-taxonomy.md)
- [배포 구조](docs/architecture/deployment.md)
- [Argo CD 구조와 stage gate](docs/architecture/argocd.md)
- [Secret trust boundary](docs/architecture/secret-trust.md)
- [Terraform 사용 경계](docs/architecture/terraform.md)
- [빈 dev 클러스터 bootstrap](docs/runbooks/dev-bootstrap.md)
- [Application 안전한 decommission](docs/runbooks/application-decommission.md)
- [Terraform state 이관](docs/runbooks/terraform-state-migration.md)
- [Vault backup/recovery](docs/runbooks/vault-backup-restore.md)
- [Sealed Secrets recovery](docs/runbooks/sealed-secrets-recovery.md)
- [입문 가이드](docs/guides/intern-guide.md)
- 직접 선언한 Application은 root 하나뿐이고, 나머지는 모두 ApplicationSet이 만든다. `default` AppProject는 쓰지 않는다.
- AppProject는 ApplicationSet 파일마다 고정했다. element 값으로 project를 바꿀 수 있으면 목록 한 줄만 고쳐서 허용되지 않은 namespace에 배포할 수 있기 때문이다. 배포 대상은 데이터로 관리하지만 권한 경계는 데이터로 만들지 않았다.
- ApplicationSet에서 element를 지워도 Application과 리소스는 바로 지워지지 않는다(`create-update`, `preserveResourcesOnDeletion`). 내릴 때는 [Application 해체 runbook](docs/runbooks/application-decommission.md)을 따른다.
### autoSync 단계 열기
ApplicationSet의 element마다 `autoSync` 값이 있다. 처음에는 Sealed Secrets와 Vault만 켜고, 나머지는 선행 조건을 확인한 뒤 PR로 하나씩 켠다.
Application 사이의 순서를 sync wave로 맞추지 않은 이유가 있다. root Application 안의 wave는 AppProject(`-10`)를 ApplicationSet(`-5`)보다 먼저 만드는 데까지만 쓰이고, 앞선 Application이 정상 상태가 될 때까지 기다려 주지는 않는다. `autoSync`가 꺼진 Application도 생성은 되므로 diff를 먼저 볼 수 있다.
켜는 순서와 각 단계의 선행 조건은 다음과 같다. 전체 절차는 [dev bootstrap runbook](docs/runbooks/dev-bootstrap.md)에 있다.
1. `vault-agent-injector`: Vault 초기화, `vault-foundation`·`vault-workloads` 적용, runtime secret 입력을 마친 뒤
2. `auth-system`: Injector 동작, workload policy와 secret 존재를 확인한 뒤
3. `auth-server`: `vault-database` 적용, Keycloak client 동기화와 DB migration credential을 확인하고 최초 root token을 폐기한 뒤
4. `api-server`: `auth-server`가 정상 동작하는 것을 확인한 뒤
`auth-server`와 `api-server`는 GHCR pull secret(SealedSecret)을 쓴다. 이 두 단계를 열기 전에 Sealed Secrets controller key를 복원하거나 새 key로 다시 seal해 둬야 한다([Sealed Secrets runbook](docs/runbooks/sealed-secrets-recovery.md)).
한 PR에서 여러 단계를 같이 열지 않고, 각 PR에서 `scripts/project-validate.sh`의 개수 검사도 함께 고친다.
## Vault
Vault는 `vault` namespace에 한 대만 띄운다. 저장소는 integrated Raft이고 listener는 TLS 없는 HTTP다. 예전에는 auto-unseal용 Vault를 따로 두었지만, 두 대가 같은 단일 노드에 있어 장애 범위가 나뉘지 않았고 초기화와 credential 관리만 늘어서 한 대로 줄였다.
그래서 Vault가 재시작하면 직접 unseal한다. 운영자 PC에서 port-forward를 열어 두고, 다른 터미널에서 unseal을 실행한다.
```bash
kubectl -n vault port-forward deployment/vault 8200:8200
./scripts/vault-init.sh unseal
```
unseal에는 vault, jq, rg CLI와 unseal key가 든 init 결과 파일이 필요하다. 이 파일은 bootstrap 뒤 암호화 보관소로 옮기므로, unseal 전에 기본 위치(`.local/vault/dev-k3s-init.json`)에 복원하거나 `VAULT_INIT_OUTPUT`으로 위치를 지정한다. Vault 주소는 `VAULT_ADDR`(기본 `http://127.0.0.1:8200`)로 바꿀 수 있다. 최초 초기화(`init`)와 root token 폐기(`revoke-root`)는 [dev bootstrap runbook](docs/runbooks/dev-bootstrap.md) 순서대로만 실행한다.
### 애플리케이션이 secret을 받는 방식
```text
Pod ServiceAccount token (audience: vault)
─▶ Vault Kubernetes auth 로그인 (workload별 role)
─▶ Vault Agent Injector가 허용된 값만 /vault/secrets/ 아래 파일로 렌더링
─▶ 컨테이너가 시작할 때 이 파일을 읽어 환경 변수로 사용
```
- runtime secret은 Kubernetes Secret으로 만들지 않는다. 고정 Vault token도 Git이나 Secret에 두지 않는다.
- `auth-server`는 Agent가 받아 온 Vault token으로 Transit API를 호출해 JWT를 서명한다.
- DB migration Job(`auth-db-migration`)은 Argo CD Sync hook으로 `auth-server` Deployment보다 먼저 실행되고, Vault database secrets engine이 발급한 짧은 수명의 DB 계정을 쓴다.
- 예외는 GHCR image pull credential(`ghcr-regcred`) 하나다. 이미지는 Pod가 뜨기 전에 받아야 하는데 Vault Agent는 Pod가 만들어진 뒤에 동작하므로, 이 값만 SealedSecret으로 Git에 둔다.
### Vault KV 경로
```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
```
KV 경로도 `gitops/` 디렉터리처럼 `systems`와 `workloads`로 나눴다. policy와 Agent annotation에는 KV v2 API 경로(`kv/data/dev/...`)를 쓰고, CLI로 값을 넣을 때는 `vault kv put kv/dev/...` 형태를 쓴다. 두 경로를 섞어 쓰면 policy가 맞지 않으니 주의한다.
## Terraform
Terraform은 Kubernetes가 아니라 Vault 안의 객체만 관리한다. state는 변경 빈도와 필요한 권한에 따라 세 개로 나눴다.
| state | 관리 대상 | 실행 권한 |
|---|---|---|
| `vault-foundation` | KV·database·Transit mount, Kubernetes auth backend, 다른 state용 위임 policy | bootstrap 또는 보안 관리자 |
| `vault-workloads` | workload policy 5개, Kubernetes auth role, Transit 키 `project-auth-jwt` | workloads 전용 단기 token |
| `vault-database` | PostgreSQL 연결, DB migration용 dynamic role | database 전용 단기 token |
- Vault 객체 하나는 한 state에서만 관리한다.
- `vault-workloads`와 `vault-database`는 자기 실행 권한을 주는 policy나 login role을 만들지 않는다. 위임 policy는 `vault-foundation`이 관리한다.
- state 사이에 `terraform_remote_state` 의존을 두지 않는다.
- secret 값, Vault 초기화 결과, token, DB 비밀번호는 Git과 state에 남기지 않는다. DB 관리자 비밀번호는 write-only 입력으로만 넘긴다.
- backend는 S3다. 각 root의 `backend.s3.hcl.example`을 `.local/terraform-backend/dev-k3s/`로 복사해 실제 값을 채운다. 예시 설정은 암호화(`encrypt`)와 lock 파일(`use_lockfile`)을 켜 두며, credential은 파일에 넣지 않는다.
## 자주 쓰는 명령
| 명령 | 용도 |
|---|---|
| `make help` | 사용할 수 있는 target 목록 |
| `make doctor` | 로컬 도구 설치 상태 확인 |
| `make validate` | 커밋 전 정적 검증. CI의 `make check`와 같은 검사 |
| `make bootstrap` | Argo CD와 root Application 설치 (위 [Argo CD](#argo-cd) 참고) |
`make validate`에는 kubectl, helm, terraform, jq, rg(ripgrep), git이 필요하다. `make doctor`는 이 중 일부만 확인하므로 helm, jq, rg는 따로 확인한다. 검증 중에 Helm chart와 Terraform provider를 내려받으므로 네트워크도 연결돼 있어야 한다.
Vault Terraform은 저장한 plan을 검토한 뒤 그 plan만 적용한다. Vault 주소와 token은 `TF_VAR_vault_addr`, `TF_VAR_vault_token` 환경 변수로 넘긴다. `vault-database`는 PostgreSQL 관리자 비밀번호(`TF_VAR_postgres_admin_password`, `TF_VAR_postgres_admin_password_version`)도 실행 시점에 넘겨야 한다.
```bash
make terraform-plan TF_ROOT=vault-workloads BACKEND_CONFIG=.local/terraform-backend/dev-k3s/vault-workloads.s3.hcl
make terraform-apply TF_ROOT=vault-workloads BACKEND_CONFIG=.local/terraform-backend/dev-k3s/vault-workloads.s3.hcl APPROVE_APPLY=dev-k3s/vault-workloads
```
- `TF_ROOT`에는 `vault-foundation`, `vault-workloads`, `vault-database`만 쓸 수 있다.
- plan 파일은 `.local/terraform-plans/`에 저장된다. apply는 이 파일이 없으면 실행되지 않고, 적용한 뒤 파일을 지운다.
- `APPROVE_APPLY` 값이 `dev-k3s/` 뒤에 `TF_ROOT`를 붙인 값과 같아야 apply가 실행된다.
- auto-approve나 destroy용 target은 만들지 않았다.
## 현재 한계
- dev 전용 구성이다. Vault, PostgreSQL(`sslmode=disable`), ingress 모두 TLS 없이 동작한다.
- 전체 워크로드가 노드 하나에 올라간다. 노드가 내려가면 전부 함께 멈춘다.
- production overlay와 Application은 없다. production은 dev-k3s를 복사해서 만들지 않고, TLS, 가용성, secret 관리, 백업, 승인 절차를 따로 설계한 뒤 만든다.
- Istio는 넣지 않았다.
## 운영 문서
| 문서 | 언제 보나 |
|---|---|
| [dev-bootstrap.md](docs/runbooks/dev-bootstrap.md) | 빈 dev 클러스터를 처음부터 올릴 때 |
| [application-decommission.md](docs/runbooks/application-decommission.md) | ApplicationSet이 만든 Application을 내릴 때 |
| [terraform-state-migration.md](docs/runbooks/terraform-state-migration.md) | 예전 Vault state를 세 state로 옮길 때 |
| [vault-backup-restore.md](docs/runbooks/vault-backup-restore.md) | Vault snapshot 백업과 복구 |
| [sealed-secrets-recovery.md](docs/runbooks/sealed-secrets-recovery.md) | Sealed Secrets controller key 백업과 복구 |
저장소에 두면 안 되는 항목과 secret 취급 규칙은 [SECURITY.md](SECURITY.md)에 있다.