project-gitops
Project Auth를 개발용 Kubernetes 클러스터 dev-k3s에 배포하는 GitOps 저장소다. auth-server, api-server와 이를 받치는 Keycloak, PostgreSQL, Vault의 배포 선언과 Vault 설정을 여기서 관리한다.
애플리케이션 소스와 이미지 빌드는 각 애플리케이션 저장소가 맡는다. 이 저장소에는 Kubernetes manifest, Argo CD 설정, Vault를 설정하는 Terraform 코드와 운영 절차만 둔다.
배포 기준 저장소는 내부 Gitea의 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 설정은 서로 다른 경로로 반영한다.
Kubernetes 리소스
애플리케이션 저장소 CI ─▶ GHCR 이미지 ─▶ 이미지 변경 PR ─▶ CI 검증 ─▶ main ─▶ Argo CD ─▶ dev-k3s
(Argo CD는 autoSync가 켜진 Application만 자동 반영한다)
Vault 설정
Terraform 변경 PR ─▶ CI 검증 ─▶ 운영자가 plan 저장·검토 ─▶ 저장한 plan apply ─▶ Vault API
- CI 검증은 PR과
mainpush마다 Gitea Actions가make check를 실행하는 단계다(validate.yaml). - Argo CD 안에서 Terraform을 실행하지 않고, CI가 kubectl apply로 클러스터를 직접 바꾸지도 않는다. 같은 리소스를 두 도구가 함께 관리하면 서로의 변경을 되돌리고, Argo CD가 Terraform까지 맡으면 Vault 관리자 권한과 state lock까지 떠안게 되기 때문이다.
이미지 반영
이미지는 각 애플리케이션 저장소에서 빌드해 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)를 수동 실행한다.
- 입력: 대상 서비스(
auth-server또는api-server)와sha256:으로 시작하는 이미지 digest - 동작:
gitops/clusters/dev-k3s/overlays/workloads/아래 해당 서비스의kustomization.yaml이미지를 digest로 바꾼 브랜치를 만들고 PR을 연다.main에는 직접 push하지 않는다.
지금 overlay에는 이전 방식의 짧은 commit tag(auth-server는 1f47f2c, api-server는 fd097c9)가 남아 있다. registry에서 digest를 확인할 credential이 없어 임의로 바꾸지 않았고, 다음 promotion 때 digest로 바뀐다. 그때까지 검증 스크립트는 digest 또는 commit 형태의 tag만 허용한다.
저장소 구조
디렉터리는 제품 이름이 아니라 수명주기와 관리 책임을 기준으로 나눴다.
bootstrap/
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/ 재사용 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/ 저장소 수준 테스트 계획
gitops/ 안은 누가 쓰는지로 나눈다. 여러 서비스가 함께 쓰는 것은 platform, Project Auth 안에서만 쓰는 backing service는 systems, 별도 저장소에서 빌드하는 애플리케이션은 workloads다. 예를 들어 Keycloak은 지금 Project Auth만 쓰므로 gitops/apps/systems/auth-system/에 있다. 여러 서비스가 Keycloak을 공유하고 관리 주체가 갈라지면 platform으로 옮긴다.
_template/ 디렉터리는 새 항목을 만들 때 복사하는 원본이며 Argo CD 배포 대상이 아니다. gitops/policies/, gitops/tenants/, infrastructure/stacks/에는 아직 _template/만 있다.
base와 overlay
base/에는 환경과 무관한 설정을 두고, dev-k3s에서만 쓰는 값(namespace, host, image, Vault annotation, NetworkPolicy)은 gitops/clusters/dev-k3s/overlays/에 둔다. Argo CD는 base를 직접 배포하지 않고 이 overlay를 읽는다.
아직 base에 남은 dev 전용 설정이 있다. Keycloak의 start-dev, Vault의 TLS 비활성화와 고정 node_id다. 두 번째 클러스터를 만들 때는 이 값부터 overlay로 옮겨야 한다. Vault NetworkPolicy의 Kubernetes API CIDR와 node 주소는 overlay에 있지만 dev-k3s 값이므로 다른 클러스터에 그대로 복사하지 않는다.
새 항목을 둘 위치
| 추가할 것 | 위치 |
|---|---|
| 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 |
위치에 파일을 추가하는 것만으로 끝나지 않는 경우가 있다.
- 새 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개)도 함께 고친다.
Argo CD
평소 변경은 Git PR로만 한다. 클러스터에 직접 적용하는 것은 최초 bootstrap과 runbook에 적힌 복구·해체 절차뿐이다.
bootstrap은 대상 클러스터의 context 이름을 확인한 뒤, 그 이름을 직접 적어 실행한다. 아래의 dev-k3s는 예시이므로 첫 명령에서 확인한 실제 context 이름으로 바꾼다.
kubectl config get-contexts
make bootstrap KUBE_CONTEXT=dev-k3s
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을 적용한다.
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개
- 직접 선언한 Application은 root 하나뿐이고, 나머지는 모두 ApplicationSet이 만든다.
defaultAppProject는 쓰지 않는다. - AppProject는 ApplicationSet 파일마다 고정했다. element 값으로 project를 바꿀 수 있으면 목록 한 줄만 고쳐서 허용되지 않은 namespace에 배포할 수 있기 때문이다. 배포 대상은 데이터로 관리하지만 권한 경계는 데이터로 만들지 않았다.
- ApplicationSet에서 element를 지워도 Application과 리소스는 바로 지워지지 않는다(
create-update,preserveResourcesOnDeletion). 내릴 때는 Application 해체 runbook을 따른다.
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에 있다.
vault-agent-injector: Vault 초기화,vault-foundation·vault-workloads적용, runtime secret 입력을 마친 뒤auth-system: Injector 동작, workload policy와 secret 존재를 확인한 뒤auth-server:vault-database적용, Keycloak client 동기화와 DB migration credential을 확인하고 최초 root token을 폐기한 뒤api-server:auth-server가 정상 동작하는 것을 확인한 뒤
auth-server와 api-server는 GHCR pull secret(SealedSecret)을 쓴다. 이 두 단계를 열기 전에 Sealed Secrets controller key를 복원하거나 새 key로 다시 seal해 둬야 한다(Sealed Secrets runbook).
한 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을 실행한다.
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 순서대로만 실행한다.
애플리케이션이 secret을 받는 방식
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-serverDeployment보다 먼저 실행되고, Vault database secrets engine이 발급한 짧은 수명의 DB 계정을 쓴다. - 예외는 GHCR image pull credential(
ghcr-regcred) 하나다. 이미지는 Pod가 뜨기 전에 받아야 하는데 Vault Agent는 Pod가 만들어진 뒤에 동작하므로, 이 값만 SealedSecret으로 Git에 둔다.
Vault KV 경로
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 참고) |
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)도 실행 시점에 넘겨야 한다.
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 | 빈 dev 클러스터를 처음부터 올릴 때 |
| application-decommission.md | ApplicationSet이 만든 Application을 내릴 때 |
| terraform-state-migration.md | 예전 Vault state를 세 state로 옮길 때 |
| vault-backup-restore.md | Vault snapshot 백업과 복구 |
| sealed-secrets-recovery.md | Sealed Secrets controller key 백업과 복구 |
저장소에 두면 안 되는 항목과 secret 취급 규칙은 SECURITY.md에 있다.