# 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](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 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과 `main` push마다 Gitea Actions가 `make check`를 실행하는 단계다([validate.yaml](.gitea/workflows/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](.gitea/workflows/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만 허용한다. ## 저장소 구조 디렉터리는 제품 이름이 아니라 수명주기와 관리 책임을 기준으로 나눴다. ```text 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 이름으로 바꾼다. ```bash 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`을 적용한다. ```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개 ``` - 직접 선언한 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)에 있다.