refactor: Readme 수정 및 불필요한 문서 정리
This commit is contained in:
@@ -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)에 있다.
|
||||
|
||||
Reference in New Issue
Block a user