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
+3
View File
@@ -20,6 +20,9 @@
its own execution identity.
- Routine GitOps automation changes Git only; direct cluster mutation is
reserved for documented bootstrap and recovery runbooks.
- Keep design rationale, ADRs and troubleshooting history in the document-haness
SSOT (`docs/project-gitops/final/document.md`); this repository keeps only
configuration descriptions and runbooks.
- Run `make validate` before handing off repository changes.
- Do not apply to a live cluster unless the user explicitly requests live
deployment and the kube context has been verified.
-72
View File
@@ -1,72 +0,0 @@
# Changelog
## 2026-07-26
- Adopted the `k8s-template` lifecycle layout: bootstrap under
`bootstrap/gitops`, Terraform under `infrastructure`, all Kubernetes desired
state under `gitops`, automation under `scripts`, and ADRs under
`docs/decisions`.
- Made `gitops/clusters/dev-k3s` the root Application source while preserving
permission-scoped ApplicationSets and their staged `autoSync` gates.
- Co-located reusable Terraform modules in `infrastructure/components`,
backend examples with each live root, and Vault ACLs with their owning
Terraform state.
- Added the template catalogs, `_template` directories, examples, security
checks, and common validation ahead of project-specific validation.
- Clarified that this repository is an independent GitOps reference lab, not a
shared production platform or an application source monorepo.
- Reclassified Kubernetes ownership as `platform`, `systems` and `workloads`;
moved the Project Auth PostgreSQL/Keycloak boundary to
`systems/auth-system`.
- Replaced generic cluster `manifests` with ownership-aligned
`clusters/dev-k3s/overlays`.
- Moved the Argo control-plane inventory to
`platform/control-plane/argocd` and separated permission-scoped AppProjects
for addons, shared services, systems and workloads.
- Added a bootstrap-only `gitops-control-plane` AppProject so the root no
longer reconciles through Argo CD's unrestricted `default` project.
- Replaced repeated child Application definitions with strict
list-generated ApplicationSets and explicit `autoSync` bootstrap gates.
- Renamed the Project Auth backing-system namespace to `auth-system-dev` and
aligned service DNS, NetworkPolicy and ConfigMap ownership.
- Changed Vault KV ownership from legacy `dev/platform` paths to
`dev/systems/auth-system` and `dev/workloads/auth-server` paths.
- Split the broad `vault-core` ownership into `vault-foundation` and
`vault-workloads`, retaining `vault-database` as a third isolated state.
- Documented delegated Terraform identities, stage-by-stage bootstrap and
non-destructive state/path migration procedures.
- Kept GHCR as the image artifact boundary and made immutable digests the
promotion target; existing short commit tags remain until a registry-verified
promotion PR replaces them.
- Performed repository-only refactoring and static validation; no Kubernetes,
Vault, Argo CD, registry or remote Terraform backend was mutated.
## 2026-07-25
- Established the internal Gitea repository as the single GitOps source.
- Replaced staged Argo roots with one bootstrap seed and one cluster-owned
root Application.
- Reorganized the repository around `clusters/dev-k3s`, environment-neutral
`platform`/`workloads` bases and separate `iac/terraform`.
- Corrected the Sealed Secrets Helm repository and added controller resources
and key renewal configuration.
- Removed incomplete production skeletons; production remains unsupported.
- Changed application promotion to a Gitea pull request carrying an immutable
OCI digest and removed direct writes to `main`.
- Pinned Vault, PostgreSQL, Keycloak, Vault Injector and Sealed Secrets images
to verified multi-architecture digests.
- Removed routine `kubectl apply`, port-forward orchestration and reusable
Vault operator-token scripts.
- Added a guarded, dev-only Vault init/unseal/root-revoke entrypoint.
- Fixed auth migration and Keycloak sync Job lifecycle and ordering.
- Removed selective sync from Applications containing Sync hooks.
- Enabled ConfigMap hash rollouts and projected Vault authentication tokens.
- Removed the same-cluster Transit Vault and its credential rotation cycle.
- Consolidated Terraform into `vault-core` and `vault-database` remote states
with write-only/ephemeral credential inputs.
- Removed tracked Terraform providers and backend metadata.
- Moved machine-consumed Vault policies out of runbooks and narrowed routine
automation permissions.
- Recorded Gateway API first and deferred Istio ambient adoption criteria.
- Reduced shell entrypoints from 18 files/1,205 lines to 3 files/300 lines.
- Split current documentation from archived historical material.
-32
View File
@@ -1,32 +0,0 @@
# 기여 가이드
## 변경 원칙
1. 변경 대상의 소유 디렉터리를 먼저 확인합니다.
2. 재사용 가능한 구현은 catalog 영역에, 환경별 조합과 차이만 live/cluster
진입점에 둡니다.
3. 하나의 리소스는 하나의 도구와 하나의 디렉터리만 소유합니다.
4. 운영 변경에는 영향 범위, 롤백 방법, 검증 결과를 함께 기록합니다.
5. `make check`를 통과한 변경만 리뷰를 요청합니다.
## 이름 규칙
- 폴더와 리소스: 소문자 `kebab-case`
- 환경: `dev`, `staging`, `prod`처럼 조직에서 합의한 고정 어휘
- 클러스터: 환경과 위치를 식별할 수 있는 안정적인 이름
- 임시 이름, 사람 이름, 티켓 번호를 장기 리소스 이름에 사용하지 않음
## Pull request 체크리스트
- [ ] 변경이 올바른 소유권 경계에 위치한다.
- [ ] 비밀, kubeconfig, state, plan 파일이 포함되지 않았다.
- [ ] 공급자, module, chart, image 버전 변경의 영향을 확인했다.
- [ ] `make check` 결과를 확인했다.
- [ ] 운영 영향이 있으면 rollback/runbook을 갱신했다.
- [ ] 구조적 선택이 바뀌면 ADR을 추가하거나 갱신했다.
## 배포
Kubernetes routine 변경은 Git PR로만 반영합니다. Terraform apply는
`TF_ROOT`, backend config, 검토된 saved plan과 `APPROVE_APPLY`가 모두
준비된 경우에만 실행합니다. `destroy` 진입점은 제공하지 않습니다.
+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)에 있다.
-159
View File
@@ -1,159 +0,0 @@
# Argo CD architecture
## Control-plane ownership
Controller 설치 후 다음 두 bootstrap object를 순서대로 수동 seed합니다.
1. `bootstrap/gitops/argocd/control-plane-project.yaml`
2. `bootstrap/gitops/argocd/root-application.yaml`
`gitops-control-plane` AppProject는 canonical Gitea repository와 in-cluster
`argocd` namespace, AppProject/ApplicationSet kind만 허용합니다. 단일 root
Application은 이 Project를 사용하고 `gitops/clusters/dev-k3s`를 source로
사용합니다. Cluster root는 다음 control-plane 구성을 참조합니다.
```text
gitops/platform/control-plane/argocd
├── projects
│ ├── platform-addons.yaml
│ ├── platform-services.yaml
│ ├── systems.yaml
│ └── workloads.yaml
└── application-sets
├── platform-addons.yaml
├── platform-services.yaml
├── systems.yaml
└── workloads.yaml
```
Cluster root는 AppProject와 ApplicationSet까지만 직접 소유합니다. 각
ApplicationSet의 list inventory가 실제 child Application을 생성합니다.
Routine 변경에 category별 root나 직접 `kubectl apply`를 추가하지 않습니다.
## AppProject boundary
| AppProject | 소유 범위 | 허용 destination |
|---|---|---|
| `platform-addons` | Sealed Secrets, Vault Agent Injector 같은 외부 cluster addon | `kube-system`, `vault` |
| `platform-services` | 저장소가 소유하는 Vault shared service | `vault` |
| `systems` | Project Auth 전용 PostgreSQL, Keycloak, sync job | `auth-system-dev` |
| `workloads` | first-party `auth-server`, `api-server` | `auth-dev`, `api-dev` |
Project는 ApplicationSet 파일마다 고정하며 inventory 값으로 template하지
않습니다. 이렇게 해야 element 변경으로 권한 경계를 넘을 수 없습니다.
각 Project는 필요한 source repository, destination, resource kind만
allowlist합니다.
## ApplicationSet contract
ApplicationSet은 strict Go template와 list generator를 사용합니다.
- `goTemplate: true`
- `goTemplateOptions: ["missingkey=error"]`
- 공통 element: `component`, `cluster`, `server`, `namespace`, quoted string
`autoSync`
- Git source element: ownership grammar를 따르는 `path`; `targetRevision`은
template의 `main`으로 고정
- Helm addon element: allowlisted `repoURL`, `chart`, chart `revision`,
`helmValues`
- 파일별 고정 project
필수 key가 빠지면 빈 문자열로 잘못 배포하지 않고 render가 실패해야 합니다.
Application 이름, destination, source path는 같은 element에서 파생하되
project와 Git repository/revision trust boundary는 template하지 않습니다.
외부 addon의 Helm `repoURL`은 element에서 template되지만 고정 AppProject의
`sourceRepos` allowlist 밖 URL은 sync할 수 없습니다.
## `autoSync` stage gate
`autoSync`는 bootstrap 준비 상태와 routine reconciliation을 분리합니다.
Inventory schema는 Go template 비교를 위해 boolean이 아닌 quoted string
`"true"`/`"false"`를 사용합니다. Template patch는 값이 `"true"`인
element에만 다음 정책을 추가합니다.
```yaml
syncPolicy:
automated:
enabled: true
prune: true
selfHeal: true
```
초기 gate는 다음과 같습니다.
| Application | 초기 `autoSync` | 열기 전 확인 |
|---|---:|---|
| Sealed Secrets | `"true"` | Argo가 chart source를 읽을 수 있음 |
| Vault | `"true"` | dev PVC와 NetworkPolicy 변경 검토 |
| Vault Agent Injector | `"false"` | Vault init, `vault-foundation`, `vault-workloads`, runtime secret seed 완료 |
| `auth-system` | `"false"` | Injector Healthy와 Vault login/secret capability 확인 |
| `auth-server` | `"false"` | PostgreSQL Healthy, `vault-database`, Keycloak/sync 준비 완료 |
| `api-server` | `"false"` | `auth-server` Healthy와 호출 경로 확인 |
Gate는 단계별 PR로 하나씩 엽니다. `false`여도 Application 생성과 diff
표시는 계속되며 수동 Sync 자체를 기술적으로 막지는 않습니다. 따라서
Argo RBAC에서 sync 권한을 제한하고, 수동 Sync에는 명시적 change record를
요구합니다.
비활성 기간 동안 쌓인 모든 diff가 gate를 여는 순간 함께 반영됩니다.
`autoSync: "true"` PR은 현재 live-to-desired 전체 diff를 검토한 뒤
승인해야 합니다.
## Ordering과 failure handling
Control-plane sync wave는 AppProject(`-10`)를 ApplicationSet(`-5`)보다
먼저 생성합니다. 네 ApplicationSet은 모두 같은 wave이고 element별
stage/wave field는 없습니다. Generated Application의 실제 readiness
순서는 `autoSync` 전환과 health 확인이 담당합니다.
Vault Agent, workload와 hook은 선행 API가 늦게 준비될 때 retry할 수 있어야
합니다. `auth-system`의 Keycloak client sync와 `auth-server`의 database
migration은 idempotent Sync hook입니다. Hook을 사용하는 Application에는
`ApplyOutOfSyncOnly=true`를 설정하지 않습니다.
Generated Application은 automated 상태에서 `PruneLast=true`와
`FailOnSharedResource=true`를 사용합니다. ApplicationSet은
`applicationsSync: create-update`와 `preserveResourcesOnDeletion: true`를
사용합니다. Parent prune과 Application 삭제에는 확인을 요구합니다.
CRD와 cluster-wide RBAC를 포함할 수 있는 `platform-addons`는
Application-level `Prune=confirm`도 사용하므로 chart upgrade의 삭제는
별도 승인이 필요합니다.
Stateful path rename이나 ownership 이동은 별도 migration으로 수행하며
ApplicationSet element를 먼저 삭제하지 않습니다.
`create-update`에서는 generator element를 제거해도 기존 generated
Application이 자동 삭제되지 않고 stale 상태로 남습니다. Element 제거와
Application/resource decommission은
[application decommission runbook](../runbooks/application-decommission.md)의
inventory, gate, backup, 명시적 삭제 절차를 따릅니다.
## Generator 확장 기준
현재는 cluster가 `dev-k3s` 하나이므로 네 ApplicationSet의 explicit List
generator가 가장 쉽게 검토됩니다. 존재하지 않는 production이나 미래
cluster를 위해 Matrix abstraction을 미리 만들지 않습니다.
두 번째 실제 cluster가 생겨 `cluster`, `server`와 cluster별 gate를 여러
component에서 반복하게 될 때 `gitops/clusters/<cluster>/config.yaml`을 Git
files generator로 읽고 component inventory와 Matrix generator로 결합합니다.
그때도 AppProject는 ApplicationSet template에 고정하고, cluster별
`autoSync`는 quoted string과 승인 gate로 유지합니다.
## Further reading
- Argo CD: [cluster bootstrapping](https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/),
[ApplicationSet modification policy](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Controlling-Resource-Modification/),
[ApplicationSet deletion](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Application-Deletion/),
[automated sync semantics](https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/)
- Kubernetes:
[Kustomize](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/)
- Terraform: [state refactoring](https://developer.hashicorp.com/terraform/language/state/refactor),
[`terraform_remote_state` security warning](https://developer.hashicorp.com/terraform/language/state/remote-state-data),
[write-only arguments](https://developer.hashicorp.com/terraform/language/manage-sensitive-data/write-only)
- Vault:
[JWT/OIDC authentication](https://developer.hashicorp.com/vault/docs/auth/jwt)
## Repository-only change
이 구조와 gate 설계는 2026-07-26 현재 Git에서만 작성·검증했습니다. 실제
cluster migration이나 sync는 이 리팩터링 리뷰 범위에 포함되지 않습니다.
-119
View File
@@ -1,119 +0,0 @@
# Deployment architecture
## Reconciliation boundaries
```text
Gitea main
|
+-- Argo CD root
| -> AppProjects + ApplicationSets
| -> generated Applications
| -> Kubernetes
|
+-- approved Terraform runner
-> one of three Vault states
-> Vault API
```
Argo CD는 Kubernetes desired state만 관리합니다. 최초 Argo 설치와
bootstrap 전용 AppProject/root seed, 문서화된 recovery 외에는 직접
cluster mutation을 하지 않습니다. Terraform은 Config Management
Plugin이나 Argo hook 안에서 실행하지 않습니다. GHCR은 image artifact
registry이며 desired state source가 아닙니다.
## Kubernetes ownership
| Layer | 역할 |
|---|---|
| `gitops/clusters/dev-k3s` | bootstrap root가 읽는 유일한 cluster entrypoint |
| `gitops/platform/control-plane/argocd` | AppProject와 ApplicationSet control plane |
| `gitops/platform/shared-services/*/base` | 환경 중립을 목표로 하는 공유 cluster service base |
| `gitops/apps/systems/*/base` | 환경 중립을 목표로 하는 bounded-context backing system base |
| `gitops/apps/workloads/*/base` | first-party 애플리케이션 base |
| `gitops/clusters/dev-k3s/overlays/*` | dev namespace, host, digest, Vault role/path, NetworkPolicy를 합친 최종 구성 |
현재 concrete ownership은 Vault가 platform shared service,
PostgreSQL/Keycloak이 `gitops/apps/systems/auth-system`, 두 서버가
`gitops/apps/workloads`의 workload입니다.
Argo CD Application은 base가 아니라 최종 cluster overlay만 source로
사용합니다.
현재 Keycloak base의 `start-dev`와 Vault base의
TLS-off/single-node identity는 dev-specific 예외입니다. 내부 Service
참조는 짧은 DNS로 namespace 중립화했지만, 남은 값을 overlay로 추출하는
작업은 후속 리팩터링입니다.
지원하지 않는 production overlay는 존재하지 않습니다. Production trust,
approval, TLS, availability contract가 확정될 때 별도로 설계합니다.
## Bootstrap progression
```text
Argo root
-> Sealed Secrets + Vault autoSync
-> Vault init
-> vault-foundation
-> vault-workloads
-> runtime secret seed
-> Vault Agent Injector autoSync gate
-> auth-system autoSync gate
-> PostgreSQL Healthy
-> vault-database
-> Keycloak/client sync ready
-> auth-server autoSync gate
-> auth-server Healthy
-> api-server autoSync gate
```
이 순서는 Application sync wave로 강제하지 않습니다. 각 전환은 health와
plan/diff를 확인한 별도 PR입니다. Gate가 닫힌 동안에도 generated
Application은 OutOfSync diff를 보여 줍니다.
## In-application ordering
`auth-server`의 한 sync operation 안에서는 다음 ordering을 사용합니다.
- 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을 사용합니다.
Application 간 준비 순서와 Application 내부 hook 순서를 혼동하지
않습니다.
## Stateful lifecycle
Vault PVC에는 `Prune=confirm,Delete=confirm`이 명시되어 있습니다.
PostgreSQL PVC는 StatefulSet `volumeClaimTemplates`가 생성하며 현재
manifest에 별도 Argo prune annotation이 없습니다. Namespace와 generated
Application 삭제 보호만 믿지 말고 PostgreSQL retention/backup을 직접
확인해야 합니다. Path, namespace, Application 이름을 이동할 때는 다음을
별도 migration으로 다룹니다.
1. 기존 live object와 owner를 inventory합니다.
2. 새 owner가 같은 object를 안전하게 추적할 수 있는지 render/diff로
확인합니다.
3. Stateful data backup과 rollback 지점을 확보합니다.
4. 기존 owner를 non-cascading 방식으로 제거한 뒤 새 owner를 연결합니다.
이번 리팩터링에서는 `platform` namespace의 auth-system을
`auth-system-dev`로 옮기는 live 작업을 실행하지 않았습니다.
## Image promotion과 GHCR
정상 promotion에서 first-party image CI는 검증한 정확한 GHCR digest를
Gitea workflow에 전달합니다. Workflow는 전용 branch와 digest 변경 PR을
만들고 validation과 승인을 거쳐 merge된 뒤 Argo CD가 배포합니다.
Renovate는 외부 chart, third-party image와 Terraform provider만 갱신하며
두 first-party GHCR package는 비활성화합니다. 따라서 동일 image field를
promotion workflow와 Renovate가 동시에 쓰지 않습니다.
Private GHCR pull credential만 SealedSecret으로 Git에 저장합니다. 평문
credential이나 registry token은 manifest, Actions log, Terraform state에
남기지 않습니다.
현재 short-SHA tag는 migration 시점의 예외입니다. Registry 검증 없이
임의 digest를 만들지 않고 다음 정상 promotion에서 immutable digest로
교체합니다.
-150
View File
@@ -1,150 +0,0 @@
# Repository Structure
## 설계 목표
이 구조는 특정 제품의 파일 배치보다 변경 주기와 소유권을 우선합니다.
- 한 리소스에는 한 명확한 소유자가 있다.
- 재사용 구현과 실제 배포 진입점을 분리한다.
- 소규모 구성은 선택 영역을 생략할 수 있다.
- 규모가 커져도 기존 경계를 바꾸지 않고 같은 종류의 leaf를 추가한다.
- 사람이 실행하는 명령과 CI 검증이 같은 진입점을 사용한다.
## 소유권 매트릭스
| 대상 | 소유 경로 | 직접 실행 여부 | 변경 주기 |
|---|---|---:|---|
| state backend, 초기 identity | `bootstrap/foundation` | 예 | 매우 낮음 |
| 네트워크, IAM, DNS, 클러스터 | `infrastructure/live` | 예 | 낮음 |
| 재사용 IaC 단위 | `infrastructure/components` | 아니요 | 중간 |
| 재사용 IaC 조합 | `infrastructure/stacks` | 아니요 | 중간 |
| GitOps 컨트롤러와 root 연결 | `bootstrap/gitops` | 예 | 낮음 |
| 클러스터 desired state | `gitops/clusters` | reconcile 진입점 | 지속적 |
| cluster-wide addon | `gitops/platform` | 아니요 | 중간 |
| 애플리케이션 배포 정의 | `gitops/apps` | 아니요 | 높음 |
| 정책과 tenant 정의 | `gitops/policies`, `gitops/tenants` | 아니요 | 중간 |
Catalog 영역(`components`, `stacks`, `platform`, `policies`, `tenants`, `apps`)은
직접 배포하지 않습니다. 실제 진입점이 필요한 항목만 조합해서 참조합니다.
## 의존 방향
```text
bootstrap/foundation
│ output
▼
infrastructure/components ◀── infrastructure/stacks
▲ ▲
└──────── infrastructure/live ─┘
│ cluster endpoint/identity
▼
bootstrap/gitops
│ root reference
▼
platform ─┐
policies ─┼────────▶ gitops/clusters
tenants ─┤
apps ─┘
```
역방향 의존은 만들지 않습니다. 예를 들어 reusable component가 특정
`live/prod` 값을 읽거나, app base가 특정 cluster overlay를 참조하면 안 됩니다.
## Infrastructure 경계
### `components`
네트워크, identity, registry, Kubernetes cluster처럼 작고 응집된 재사용
단위입니다. Terraform/OpenTofu를 선택했다면 일반적으로 backend가 없는 child
module에 해당합니다.
### `stacks`
여러 component를 반복해서 같은 방식으로 조합할 때만 사용합니다. 작은 프로젝트는
이 계층 없이 `live`가 component를 직접 호출할 수 있습니다. stack이 다른 stack을
깊게 중첩하기보다는 live root에서 평평하게 조합하는 방식을 권장합니다.
### `live`
실제로 plan/apply하는 root입니다. leaf 하나는 다음을 만족해야 합니다.
- 독립된 state와 locking
- 명시적인 provider와 backend 설정
- 고정된 component/module/chart 버전
- 비밀이 아닌 환경 입력만 저장소에 커밋
- 출력값과 downstream contract 문서화
작은 구성은 `live/dev/cluster`로 충분합니다. 계정과 리전이 늘어나면
`live/<provider>/<account>/<region>/<environment>/<stack>`처럼 경로를 확장합니다.
자동화는 경로의 고정 깊이에 의존하지 말고 실행 가능한 root 파일을 기준으로
대상을 찾도록 작성합니다.
서로 다른 환경의 root가 상대 경로로 다른 환경 구현을 import하면 안 됩니다.
공유가 필요하면 versioned component나 명시적인 remote output/data contract를
사용합니다.
## GitOps 경계
### `clusters`
클러스터가 reconcile하는 유일한 진입점입니다. 공통 리소스를 복사하지 않고
platform, policy, tenant, app catalog에서 필요한 항목만 참조합니다.
작은 구성은 `clusters/dev/main`, 다중 리전 구성은
`clusters/<environment>/<region>/<cluster>` 형태를 사용할 수 있습니다. 여기에도
고정된 경로 깊이를 강제하지 않습니다.
### `platform`
cluster-wide controller와 addon을 둡니다. 예시는 다음과 같습니다.
- ingress/gateway, external DNS, certificate
- storage class/CSI, autoscaling
- metrics, logs, traces, alerting
- secret operator와 delivery controller
각 component는 `base`와 필요한 `overlays`를 같은 디렉터리 안에 응집시킵니다.
환경 차이는 전체 파일 복사 대신 Kustomize patch 또는 별도 values로 표현합니다.
### `policies`, `tenants`, `apps`
- `policies`: cluster-wide admission 규칙, 거버넌스와 예외
- `tenants`: 구체적인 namespace, RBAC, quota, limit range, NetworkPolicy
- `apps`: application source code가 아닌 배포 정의
애플리케이션 팀이 별도 저장소를 소유하면 `apps`에는 그 저장소/OCI artifact를
참조하는 GitOps 리소스만 둘 수 있습니다.
Cloud DNS zone/delegation과 cloud IAM role은 `infrastructure`가 소유합니다.
External DNS controller, 동적 record 요청과 Kubernetes ServiceAccount binding은
`gitops/platform`이 소유합니다. 두 계층 사이에는 zone ID, role ARN 같은
명시적인 output contract만 전달합니다.
## Bootstrap 경계
Bootstrap은 선언형 관리가 스스로 시작될 수 없는 최소 범위만 담당합니다.
- `foundation`: state backend, 최초 CI identity와 같은 선행 조건
- `gitops`: Flux 또는 Argo CD 중 선택한 컨트롤러 설치와 root reference
ingress, cert-manager, observability 같은 addon은 bootstrap이 아니라 GitOps가
소유합니다. bootstrap 이후의 변경을 계속 수동 명령으로 누적하지 않습니다.
## 규모 확장 기준
| 단계 | 추가하는 것 | 그대로 유지하는 것 |
|---|---|---|
| 소형 | 단일 live root, 단일 cluster root, 최소 platform | lifecycle/ownership 경계 |
| 중형 | reusable stack, staging/prod, 정책, 관측성 | component와 entrypoint 분리 |
| 대형 | 계정·리전별 state, 다중 cluster, tenants, CODEOWNERS | 한 리소스 한 소유자 |
| 조직 분리 | lifecycle/team별 repository 분리 가능 | 각 repository 내부의 동일한 계약 |
repository를 분리하는 시점은 폴더 수가 아니라 권한, 배포 주기와 소유 팀이
실제로 달라졌을 때입니다.
## 설계 참고 자료
- [Kubernetes: Kustomize를 이용한 선언형 객체 관리](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/)
- [Flux: GitOps repository 구조](https://fluxcd.io/flux/guides/repository-structure/)
- [OpenTofu: reusable module](https://opentofu.org/docs/language/modules/)
- [OpenTofu: 평평한 module composition](https://opentofu.org/docs/language/modules/develop/composition/)
-159
View File
@@ -1,159 +0,0 @@
# Repository taxonomy
이 문서는 새 리소스를 어느 디렉터리에 둘지 결정하는 기준입니다. 이
저장소는 Project Auth를 예제로 삼는 독립 reference lab이며, 디렉터리
이름은 조직의 중요도나 설치 순서가 아니라 소유권을 표현합니다.
## 분류 기준
| 분류 | 판단 질문 | 현재 예 |
|---|---|---|
| `gitops/platform` | GitOps control plane이거나, 둘 이상의 system이 독립 lifecycle로 소비할 cluster capability인가? | Argo inventory, Vault shared service |
| `gitops/apps/systems` | 하나의 bounded context가 함께 소유하는 backing system인가? | Project Auth의 PostgreSQL, Keycloak, realm/client sync |
| `gitops/apps/workloads` | 별도 source repository에서 빌드하는 first-party 실행 단위인가? | `auth-server`, `api-server` |
| `gitops/clusters` | 특정 클러스터의 최종 composition 값인가? | namespace, host, digest, Vault role, NetworkPolicy |
| `infrastructure` | Kubernetes가 아닌 외부 API 객체를 선언하는가? | Vault mounts, policies, auth roles, database roles |
| `bootstrap` | GitOps controller가 존재하기 전에 필요한 최소 seed인가? | Argo CD 설치 버전, 제한된 control-plane AppProject와 root Application |
다음 세 질문을 순서대로 사용합니다.
1. 누가 소비하고 장애 영향을 받는가?
2. 누가 변경을 승인하고 lifecycle을 책임지는가?
3. 다른 bounded context와 독립적으로 교체하거나 배포할 수 있는가?
제품 이름만으로 분류하지 않습니다. 예를 들어 Keycloak이 여러 system의
공용 identity service가 되고 별도 owner와 release cadence를 갖게 되면
실행 서비스는 `gitops/platform/`으로 이동할 수 있습니다. 그래도 Project
Auth realm/client 구성은 `gitops/apps/systems/auth-system/`에 남습니다.
현재 Keycloak과 PostgreSQL은 Project Auth 전용이므로 모두 system
소유입니다.
## Path contract
환경 중립 base와 cluster-specific overlay를 분리하는 것이 목표
contract입니다.
```text
gitops/platform/shared-services/<name>/base
gitops/apps/systems/<system>/base
gitops/apps/workloads/<workload>/base
gitops/clusters/<cluster>/overlays/platform/<name>
gitops/clusters/<cluster>/overlays/systems/<system>
gitops/clusters/<cluster>/overlays/workloads/<workload>
gitops/platform/control-plane/argocd/projects
gitops/platform/control-plane/argocd/application-sets
```
Base에는 재사용 가능한 workload 구조, Service, ServiceAccount와 기본
configuration contract를 둡니다. Overlay에는 다음처럼 클러스터와 환경을
알아야 하는 값을 둡니다.
- namespace와 public/internal host
- image reference; 정상 promotion의 목표는 immutable digest
- Vault auth role과 KV path annotation
- NetworkPolicy의 namespace/CIDR
- dev-only resource profile와 TLS 차이
Argo CD는 base를 직접 source로 사용하지 않고 반드시 최종 overlay를
reconcile합니다.
현재 first-party overlay의 짧은 commit tag는 이관 예외입니다. Registry를
검증할 credential 없이 임의 digest로 바꾸지 않고 다음 정상 promotion
PR에서 immutable digest로 전환합니다.
### 현재 base의 알려진 예외
Base 내부의 PostgreSQL·Keycloak 참조는 namespace를 포함하지 않은 짧은
Service DNS를 사용하므로 overlay namespace에 재사용할 수 있습니다. 다만
아직 다음 dev/single-node 가정은 남아 있습니다.
- `gitops/apps/systems/auth-system/base`의 Keycloak 실행 command가
`start-dev`입니다.
- `gitops/platform/shared-services/vault/base/files/vault/vault.hcl`이
`tls_disable = 1`과 고정된 single-node `node_id`를 사용합니다.
이는 숨겨진 환경 중립성이 아니라 명시적인 리팩터링 부채입니다. 두 번째
환경이나 replica를 만들기 전에 dev 전용 command, TLS와 node identity를
overlay 또는 입력 가능한 configuration으로 옮깁니다.
```text
base -> dev-k3s overlay -> ApplicationSet inventory -> generated Application
-> Argo CD -> Kubernetes
```
## Platform 안의 두 역할
`platform` ownership에는 다음 두 종류가 있습니다.
- Cluster addon: Kubernetes API를 확장하거나 admission/control-plane
기능을 제공하는 외부 chart. 현재 Sealed Secrets와 Vault Agent Injector가
해당합니다. Inventory는
`gitops/platform/control-plane/argocd/application-sets/platform-addons.yaml`에
둡니다.
- Shared service: 일반 workload처럼 namespace에서 실행되지만 여러 system이
사용할 수 있는 capability. 현재 Vault가 해당합니다.
외부 Helm chart를 복사해 base처럼 유지하지 않습니다. chart version과
values는 Argo inventory에서 pin합니다. 저장소가 직접 소유하는 shared
service manifest만 `gitops/platform/shared-services/`에 둡니다.
`foundation`은 소유권 분류가 아닙니다. Bootstrap 때 먼저 필요하다는 뜻은
분리된 ApplicationSet category, `autoSync` gate와 runbook 순서로
표현합니다. 따라서 새로운 `foundation/` business directory를 만들지
않습니다.
## System와 workload의 경계
`gitops/apps/systems/auth-system`은 인증 bounded context가 함께 책임지는
데이터와 identity backing services입니다.
- PostgreSQL StatefulSet와 초기 database contract
- Keycloak server와 Project Auth realm
- Keycloak client synchronization
`gitops/apps/workloads/auth-server`와 `gitops/apps/workloads/api-server`는
각각 별도 source repository와 release digest가 있는 애플리케이션입니다.
Workload가 auth-system을 사용하더라도 두 lifecycle을 합치지 않습니다.
Dev namespace도 소유권을 드러냅니다.
| 소유 단위 | Namespace |
|---|---|
| Vault shared service와 injector | `vault` |
| Project Auth backing system | `auth-system-dev` |
| Auth workload | `auth-dev` |
| API workload | `api-dev` |
## Vault path grammar
KV path도 같은 소유권 언어를 사용합니다.
```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
```
Vault policy 파일에는 KV-v2 API path인 `kv/data/...`를 사용하고, CLI에는
mount-relative path인 `kv/dev/...`를 사용합니다. 이전
`kv/dev/platform/...` 경로는 legacy migration source일 뿐 새 desired
state가 아닙니다.
## 새 항목 배치 예
| 변경 | 위치 |
|---|---|
| 또 다른 공용 admission controller | `gitops/platform/control-plane/argocd/application-sets/platform-addons.yaml` |
| 공용 object storage service base | `gitops/platform/shared-services/object-storage/base` |
| Project Auth 전용 Redis | `gitops/apps/systems/auth-system/base` |
| 새 first-party worker | `gitops/apps/workloads/<worker>/base` |
| dev worker digest/secret annotation | `gitops/clusters/dev-k3s/overlays/workloads/<worker>` |
| Vault workload policy/role | `infrastructure/live/dev-k3s/vault-workloads`와 그 아래 `policies/` |
| Vault auth backend | `vault-foundation` Terraform state |
분류가 애매하면 설치 순서가 아니라 owner와 소비자 경계를 ADR에 먼저
기록합니다.
-127
View File
@@ -1,127 +0,0 @@
# Secret trust boundaries
## Dev Vault
`dev-k3s`는 workload 클러스터 안의 단일 self-hosted Vault를 사용합니다.
별도 Transit Vault는 두지 않습니다. Vault는 다음 API 객체를 제공합니다.
- KV-v2 runtime secret path
- Kubernetes auth와 workload role
- Dynamic PostgreSQL credential
- 애플리케이션 JWT signing용 Transit key
Dev Vault는 Shamir 1-of-1로 한 번 초기화하고 재시작 때 명시적으로
unseal합니다. 이는 폐기 가능한 개발 환경 전용입니다. Production에서는
managed Vault 또는 독립 failure domain의 HA integrated-Raft와 KMS/HSM
auto-unseal이 필요합니다.
## Three Terraform states
```text
vault-foundation
-> mounts/auth configuration
-> delegated automation policies
-> optional, separated CI JWT login roles
vault-workloads
-> workload policies and Kubernetes auth roles
-> project-auth-jwt Transit key
vault-database
-> auth-system PostgreSQL connection
-> auth-db-migration-dev dynamic role
```
`vault-foundation`은 routine runner가 아니라 bootstrap 또는 승인된 보안
관리자가 실행합니다. 이 state가 workloads/database automation policy를
만들고, OIDC/JWT trust가 설정됐을 때만 두 login role을 분리해 만듭니다.
Workloads/database exact claim map은 최소 한 공통 discriminator key에서
다른 값을 가져야 합니다. 실제 issuer가 그 repository/ref/job claim을
신뢰할 수 있게 발행하는지 확인하지 못하면 CI JWT auth를 활성화하지
않습니다. Delegated state는 자신에게 권한을 추가할 수 없고 맡은 정확한
Vault API path만 변경합니다.
Exact API path 허용이 runner를 완전한 sandbox로 만들지는 않습니다.
`vault-workloads` runner가 허용된 ACL policy 내용이나 Kubernetes auth role
payload를 악의적으로 바꾸면 더 강한 policy를 연결하는 권한 상승이
가능합니다. 따라서 이 runner는 신뢰된 security automation으로 취급하고,
protected branch, policy lint, saved-plan 승인과 Vault audit log를 함께
trust boundary로 사용합니다.
세 state는 `terraform_remote_state`로 연결하지 않습니다. Policy/role 이름은
checked-in contract로 공유하고 runbook 또는 CI stage가 실행 순서를
보장합니다.
Provider token과 PostgreSQL password는 ephemeral/write-only 입력으로만
전달합니다. KV payload는 Terraform resource/data source로 읽거나 쓰지
않습니다.
## KV ownership paths
Secret path는 repository taxonomy와 같은 owner를 표현합니다.
| Consumer | Vault CLI path |
|---|---|
| PostgreSQL bootstrap | `kv/dev/systems/auth-system/postgres/superuser` |
| Auth database bootstrap/runtime | `kv/dev/systems/auth-system/postgres/auth-server` |
| Keycloak database | `kv/dev/systems/auth-system/postgres/keycloak` |
| Keycloak bootstrap admin | `kv/dev/systems/auth-system/keycloak/bootstrap-admin` |
| Auth-server Keycloak client | `kv/dev/workloads/auth-server/keycloak-client` |
Vault ACL과 Agent annotation은 KV-v2 API path인 `kv/data/...`를 사용합니다.
CLI의 `vault kv put`은 `kv/dev/...`를 사용합니다. 이전
`kv/dev/platform/...` 값은 migration source이며 새 policy가 계속
허용하면 안 됩니다.
## Workload authentication
Workload는 audience `vault`, TTL 1시간의 projected ServiceAccount token으로
Vault Kubernetes auth에 로그인합니다. Token은 Vault Agent가 사용하며
application container에 Kubernetes bearer token을 직접 노출하지 않습니다.
Role은 ServiceAccount, namespace, audience, token policy와 TTL을 정확히
묶습니다. 현재 role은 Project Auth backing service의 `auth-system-dev`와
Vault를 사용하는 `auth-dev` ServiceAccount에만 존재합니다. `api-dev`에는
Vault role도 Vault NetworkPolicy ingress도 없으며 필요가 생기기 전에는
권한을 추가하지 않습니다.
Secret 값은 승인된 운영자가 Vault에 직접 기록합니다. 값은 Git, Gitea
Actions log, Terraform state, Kubernetes manifest에 남기지 않습니다.
## Bootstrap material
Vault init output은 기본적으로 `.local/vault/dev-k3s-init.json`에 mode
`0600`으로 생성됩니다. Encrypted custody로 이동한 뒤 working copy를
제거합니다.
Initial root token은 다음 작업에만 사용합니다.
1. `vault-foundation` apply
2. OIDC/JWT가 없는 빈 lab의 짧은 TTL bootstrap token 발급과 capability
검증
3. 최초 runtime secret seed
4. 필요한 break-glass/recovery 절차 확인
`vault-database` 적용까지 끝나면 replacement token의 대표 update
capability와 root policy 부재를 확인한 뒤 initial root와 bootstrap token을
폐기합니다. 상시 cluster ServiceAccount에 broad `platform-admin` 정책을
연결하지 않습니다. `vault-workloads`와 `vault-database`의 routine 실행은
각각 짧은 TTL identity를 사용합니다.
Initial root 폐기 뒤에는 상시 foundation administrator가 없습니다. Future
foundation 변경은 encrypted unseal custody의 승인을 받아 Vault
generated-root ceremony를 수행하고, 승인된 plan 적용 뒤 생성한 root를
즉시 폐기해야 합니다.
Sealed Secrets는 private GHCR pull credential에만 사용합니다. Controller
private key는 Git과 분리된 recovery custody에 백업합니다.
## Dev limitations
- Vault, PostgreSQL, ingress가 TLS를 사용하지 않음
- Single-node Vault와 PostgreSQL
- Kubernetes API egress CIDR가 현재 dev cluster에 종속
- 정적 bootstrap secret은 coordinated rotation 필요
- Namespace/path migration이 아직 실제 cluster에 적용되지 않음
이 제약은 production에서 허용되지 않습니다.
-95
View File
@@ -1,95 +0,0 @@
# Terraform boundary
Terraform은 VM만 정의하는 도구가 아니라 provider가 노출하는 API 객체의
desired state를 선언하고 plan/apply하는 framework입니다. 이 저장소에는
machine/cloud provider가 없으므로 서버, 네트워크, k3s 설치를 Terraform이
소유하지 않습니다. 현재 적용 범위는 Vault API 객체뿐입니다.
## 도구별 소유권
| 대상 | 소유 도구 | 이유 |
|---|---|---|
| Kubernetes manifest와 rollout | Argo CD | Git revision을 지속적으로 reconcile |
| Vault mount, auth, policy, role, Transit key, DB connection | Terraform Vault provider | API 객체의 plan과 state ownership 필요 |
| Vault init/unseal, initial secret seed | 승인된 operator runbook | 일회성 ceremony와 secret material을 state에서 제외 |
| KV secret payload | 외부 secret authority/operator | Git과 Terraform state에 값이 남지 않아야 함 |
| VM, network, k3s | 현재 소유자 없음 | 실제 provider와 lifecycle이 정해지지 않음 |
Kubernetes와 Helm을 Terraform에 다시 넣지 않습니다. 같은 object를 Argo
CD와 Terraform이 동시에 소유하면 두 reconciler가 충돌합니다. 반대로
Terraform을 Argo hook에서 실행하면 cluster reconciliation이 Vault state
lock과 privileged credential lifecycle까지 떠안게 됩니다.
## State 경계
```text
vault-foundation
creates delegation
| |
v v
vault-workloads vault-database
runtime access PostgreSQL integration
```
- `vault-foundation`은 mount, Kubernetes auth와 위임 policy/login role을
소유합니다. Routine CI apply 대상이 아닙니다.
- `vault-workloads`는 runtime ACL/Kubernetes role과 애플리케이션 Transit
key만 소유합니다.
- `vault-database`는 실제 PostgreSQL이 준비된 뒤 connection과 migration
dynamic role만 소유합니다.
위임받은 state는 자기 runner policy나 login role을 만들지 않습니다.
State 간 이름은 checked-in contract로 공유하며 `terraform_remote_state`로
다른 state snapshot을 읽지 않습니다.
Policy HCL이 정확한 API path를 허용하므로 `kv`, `database`, `transit`,
`kubernetes`, `project-auth-jwt`, `auth-system-postgres-dev` 같은 보안
경계 이름은 각 root의 local contract로 고정합니다. 변수로 한쪽만
override해 plan은 성공하지만 권한이 어긋나는 상태를 허용하지 않습니다.
이 이름을 바꿀 때는 foundation policy, delegated root와 runtime consumer를
하나의 migration 설계에서 함께 변경합니다.
Mount, Kubernetes auth와 선택적 CI JWT auth에는 `prevent_destroy`를
적용합니다. 입력 누락이 기존 auth mount 삭제로 이어지지 않으며, 실제
제거는 consumer/token inventory를 거친 별도 decommission revision에서만
보호를 명시적으로 해제합니다.
## 실행 계약
1. Remote backend는 encryption, versioning, locking과 root별 access
control을 제공해야 합니다.
2. `terraform-plan`이 만든 saved plan을 검토하고, 같은 `PLAN_FILE`만
`terraform-apply`가 사용합니다.
3. Plan은 sensitive artifact로 취급하며 apply 성공 후 제거합니다.
4. Provider token과 PostgreSQL password는 Terraform 1.11 이상의
ephemeral variable/write-only argument로 실행 시점에 다시 주입합니다.
5. Delegated runner token은 짧은 TTL, no-default-policy와 정확한 object
path만 사용합니다. Capability 확인, self lookup과 명시적 self revoke에
필요한 세 self-service API만 별도로 허용합니다.
6. Foundation, workloads, database apply는 서로 다른 승인 단계입니다.
## 두 번째 클러스터 또는 machine IaC
두 번째 클러스터가 생겨도 state를 합치지 않습니다. Cluster별 backend와
Vault instance ownership이 독립이면 같은 세 root contract를 reusable
module로 승격합니다. 실제 VM/network provider, account, failure domain과
destroy/backup 책임이 정해졌을 때만 다음처럼 별도 machine root를
추가합니다.
```text
infrastructure/live/<cluster>/machine
infrastructure/live/<cluster>/vault-foundation
infrastructure/live/<cluster>/vault-workloads
infrastructure/live/<cluster>/vault-database
```
Machine root output을 읽기 위해 Vault state 전체를 공유하지 않습니다.
필요한 endpoint는 명시적 configuration contract나 최소 권한의 별도
configuration store로 전달합니다.
## Further reading
- [Terraform ephemeral values and write-only arguments](https://developer.hashicorp.com/terraform/language/manage-sensitive-data/ephemeral)
- [Terraform state refactoring](https://developer.hashicorp.com/terraform/language/state/refactor)
- [Remote state data security warning](https://developer.hashicorp.com/terraform/language/state/remote-state-data)
- [Vault provider write-only attributes](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/guides/using_write_only_attributes)
-97
View File
@@ -1,97 +0,0 @@
# Agent Guide
이 파일은 이 저장소에서 작업을 시작하는 사람과 에이전트를 위한 첫 진입 문서입니다.
## Read First
작업을 시작하면 아래 순서로 문서를 읽습니다.
1. 이 파일 `AGENT.md`
2. 루트 [README.md](/home/donghyeon/dev/Project-Auth-GitOps/README.md)
3. 현재 작업과 직접 관련된 runbook
- Vault transit: [runbooks/vault-transit/dev/README.md](/home/donghyeon/dev/Project-Auth-GitOps/runbooks/vault-transit/dev/README.md)
- Workload Vault: [runbooks/vault/dev/README.md](/home/donghyeon/dev/Project-Auth-GitOps/runbooks/vault/dev/README.md)
- Argo CD 구조: [argocd/README.md](/home/donghyeon/dev/Project-Auth-GitOps/argocd/README.md)
## Working Rules
- README 최상단 `현재 최신 Dev 아키텍처` 는 최신 상태로 유지합니다.
- 기존 cycle은 지우지 말고 README 맨 아래에 새 cycle을 추가합니다.
- ops 변경이나 장애 대응을 했으면 명령, 관찰, 판단 근거, 수정, 검증을 함께 남깁니다.
- 워크플로 구조를 크게 바꿨으면 README에 새 cycle을 추가합니다.
- 민감한 값은 절대 문서에 기록하지 않습니다.
- token, password, kubeconfig 본문, secret payload 금지
- 대신 존재 여부, 길이, secret name, 리소스 상태만 기록
- repo 밖 임시 파일(`/tmp/...`)로 작업한 secret manifest는 Git에 넣지 않습니다.
- Vault 관련 자동화는 **bootstrap** 과 **reconcile** 을 분리합니다.
- bootstrap: privileged token 필요, 수동 runbook
- reconcile: workflow AppRole 기반 routine CI
- GitHub Actions YAML에는 긴 Bash를 직접 넣지 않고 `scripts/ci/*.sh` wrapper로 분리합니다.
- GitHub context(`inputs`, `client_payload`) 는 inline Bash에서 직접 쓰지 않고 step `env:` 로 매핑한 뒤 스크립트에서 읽습니다.
- `scripts/ci/reconcile-vault-dev.sh` 는 기본적으로 port-forward 모드지만, 장기적으로는 `RECONCILE_USE_PORT_FORWARD=false` + in-cluster service URL로 돌리는 방향이 목표입니다.
- `vault-dev-reconcile.yaml` 은 아래 GitHub Variables 로 runner/네트워크 전환을 제어합니다.
- `VAULT_DEV_RECONCILE_RUNS_ON`
- `RECONCILE_USE_PORT_FORWARD`
- `TRANSIT_VAULT_ADDR`
- `WORKLOAD_VAULT_ADDR`
## Troubleshooting Format
README cycle의 `### 6. 트러블슈팅 메모` 에 아래 형식으로 남깁니다.
- 재현/확인 명령: 실제로 사용한 명령
- 핵심 관찰값: 에러 문구, 상태 변화, 이벤트, 로그 핵심
- 판단 근거: 왜 그 관찰값을 보고 해당 원인이라고 판단했는지
- 수정 또는 조치: 어떤 파일/리소스를 바꿨는지
- 검증 명령: 해결 여부를 다시 확인한 명령
## Current Dev Pitfalls
- Argo CD `Application` 이 `Repository not found` 를 내면 로컬 git 인증이 아니라 `argocd` namespace의 repo credential secret부터 확인합니다.
- self-hosted runner 문제는 workflow YAML보다 먼저 runner 호스트의 실제 CLI 설치 여부를 확인합니다.
- `command -v kubectl vault jq base64 curl terraform`
- Vault raft 사용 시 `api_addr`, `cluster_addr`, listener `cluster_address`, service/deployment의 `8201` 포트 일관성을 먼저 확인합니다.
- `hashicorp/vault` 이미지를 ConfigMap mount와 함께 쓸 때는 read-only mount 충돌과 단일 PVC rollout 충돌을 같이 봅니다.
- 필요하면 `/tmp` 로 config 복사 후 실행, `strategy: Recreate` 적용
- Vault Agent template에 여러 `export` 줄을 렌더링할 때는 aggressive trim(`{{- ... -}}`) 때문에 줄바꿈이 붙지 않는지 실제 `/vault/secrets/*` 파일을 확인합니다.
- Postgres PVC를 유지하는 상태에서 Vault KV만 바꾸면 DB 내부 사용자 비밀번호와 주입값이 어긋날 수 있습니다. KV 값과 persisted DB state를 함께 확인합니다.
- Headless Service를 DB connection host로 쓸 때는 pod 안에서 실제로 어떤 이름이 해석되는지 먼저 확인합니다.
- `postgres.platform.svc.cluster.local` 이 안 되면 `postgres-0.postgres.platform.svc.cluster.local` 같이 pod FQDN 확인
- CI에서 Terraform local backend를 쓰면 self-hosted runner가 기존 `.terraform-state/*.tfstate` 를 실제로 보고 있는지 먼저 확인합니다. state가 완전히 없을 때뿐 아니라 일부 리소스만 남은 partial state도 위험합니다.
- `terraform state list`
- `terraform state show <resource>`
- workflow에서 빠진 리소스를 개별 import 하도록 유지
- 단, `vault_approle_auth_backend_role_secret_id` 처럼 provider가 import를 지원하지 않는 리소스는 예외로 두고 재생성으로 수렴시킵니다.
- Vault KV-v2 mount는 provider import 결과가 `type=kv` + `options.version=2` 로 보이므로, 선언도 그 형태로 맞추고 `prevent_destroy = true` 를 유지합니다.
- seal token을 state로 다시 맞출 때는 `auth/token/revoke-accessor` 권한이 필요합니다.
- `vault_mount`, `vault_auth_backend`, `vault_token.seal` 같이 bootstrap 성격이 강한 리소스는 routine CI에서 replacement가 나지 않게 drift를 최소화합니다.
- 필요하면 `ignore_changes`
- 더 좋게는 bootstrap 단계와 reconcile 단계를 분리
- `kubectl rollout status` 실패 시 `describe`, `logs`, `events` 를 세트로 봅니다.
## Default Command Order
Argo CD app 문제:
```bash
kubectl -n argocd get applications
kubectl -n argocd describe application <name>
kubectl -n argocd get secrets
```
Runner 문제:
```bash
command -v kubectl
command -v vault
command -v terraform
```
Vault pod 문제:
```bash
kubectl -n <ns> get deploy,pods
kubectl -n <ns> describe deployment <name>
kubectl -n <ns> logs deploy/<name> --tail=200
kubectl -n <ns> get events --sort-by=.lastTimestamp | tail -n 30
```
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
-6
View File
@@ -1,6 +0,0 @@
# Archived documentation
Files in this directory describe historical repository states. Paths,
workflows, credentials and operational commands may no longer exist.
Do not execute archived procedures. Use the root README and `docs/runbooks/`.
@@ -1,8 +0,0 @@
# Legacy policies
These policies were used by permanent AppRole credentials and could modify
mounts, auth backends and their own policies. They are retained only to make
the state and credential migration auditable.
No current Terraform root references files in this directory. Revoke the
legacy AppRoles after the JWT/Kubernetes-authenticated workflow is verified.
@@ -1,59 +0,0 @@
path "transit/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "kv/data/dev/workload/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "kv/metadata/dev/workload/*" {
capabilities = ["read", "delete", "list"]
}
path "sys/internal/ui/mounts/*" {
capabilities = ["read"]
}
path "sys/mounts/*" {
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
path "sys/auth/*" {
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
path "sys/policies/acl/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "auth/approle/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "auth/token/create" {
capabilities = ["update"]
}
path "auth/token/create-orphan" {
capabilities = ["update"]
}
path "auth/token/revoke" {
capabilities = ["update"]
}
path "auth/token/revoke-accessor" {
capabilities = ["update"]
}
path "auth/token/lookup" {
capabilities = ["update"]
}
path "auth/token/lookup-accessor" {
capabilities = ["update"]
}
path "auth/token/lookup-self" {
capabilities = ["read"]
}
@@ -1,71 +0,0 @@
path "kv/data/dev/platform/postgres/superuser" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "kv/metadata/dev/platform/postgres/superuser" {
capabilities = ["read", "delete", "list"]
}
path "kv/data/dev/platform/postgres/auth-server" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "kv/metadata/dev/platform/postgres/auth-server" {
capabilities = ["read", "delete", "list"]
}
path "kv/data/dev/platform/postgres/keycloak" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "kv/metadata/dev/platform/postgres/keycloak" {
capabilities = ["read", "delete", "list"]
}
path "kv/data/dev/platform/keycloak/bootstrap-admin" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "kv/metadata/dev/platform/keycloak/bootstrap-admin" {
capabilities = ["read", "delete", "list"]
}
path "kv/data/dev/platform/keycloak/client-auth-server" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "kv/metadata/dev/platform/keycloak/client-auth-server" {
capabilities = ["read", "delete", "list"]
}
path "auth/kubernetes/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "auth/approle/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "sys/auth/*" {
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
path "sys/mounts/*" {
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
path "sys/policies/acl/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "database/config/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "database/roles/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
path "transit/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
@@ -1,12 +0,0 @@
# ADR 0001: Internal Gitea is canonical
Status: accepted
The internal repository
`https://git.learn.hyeonworks.com/donghyeon.kang/project-gitops` is the only
writable deployment source.
Argo CD and Gitea Actions use this URL. A GitHub copy may exist only as a
read-only mirror with monitored replication; it must never be an independent
deployment branch. GHCR remains an image registry and does not require GitHub
to host the GitOps source.
@@ -1,55 +0,0 @@
# ADR 0002: Terraform state ownership
Status: accepted
Updated: 2026-07-26
Terraform의 현재 범위는 Vault API 객체입니다. Kubernetes 리소스는 Argo
CD가 소유하며, machine/network provisioning은 provider와 운영 경계가
확정될 때 별도 root로 추가합니다.
`dev-k3s`는 정확히 세 state를 사용합니다.
| State | 소유 객체 |
|---|---|
| `vault-foundation` | KV/database/Transit mounts, Kubernetes auth backend/config, delegated automation policy와 선택적 분리 CI JWT auth role |
| `vault-workloads` | workload ACL policy, Kubernetes auth role, `project-auth-jwt` Transit key |
| `vault-database` | `database/config/auth-system-postgres-dev` connection과 `auth-db-migration-dev` dynamic role |
Resource 또는 Vault API path 하나는 한 state에만 속합니다. State 사이는
이름 contract와 실행 순서만 공유하며 `terraform_remote_state`로 서로의
snapshot을 읽지 않습니다. Backend는 encryption, versioning, access
control, locking을 제공해야 합니다.
Privilege delegation의 경계는 다음과 같습니다.
- `vault-foundation`은 bootstrap 또는 보안 관리자 승인 때만 실행합니다.
Routine CI identity를 두지 않습니다.
- `vault-foundation`이 workload/database 전용 automation policy와,
OIDC/JWT trust가 검증된 경우 서로 분리된 CI JWT login role을 생성합니다.
두 role의 exact claim map은 최소 한 공통 discriminator key에서 서로 다른
값을 가져야 하므로 동일 scalar-claim JWT가 둘 다 선택할 수 없습니다.
- `vault-workloads`와 `vault-database`는 각각의 short-lived identity를
소비할 뿐 자신에게 권한을 부여하는 객체를 소유하지 않습니다.
- Delegated identity는 자신이 맡은 정확한 policy, auth role, database
path만 CRUD할 수 있습니다.
- Broad `platform-admin` 또는 상시 cluster-internal Vault administrator를
routine automation에 연결하지 않습니다.
실제 CI issuer가 repository, protected ref와 job discriminator claim을
어떤 형식으로 발행하는지 먼저 검증합니다. 그 계약을 확인할 수 없으면 JWT
auth를 활성화하지 않고 bootstrap용 short-lived token만 사용합니다.
Foundation의 future change는 routine identity가 아니라 encrypted unseal
custody를 사용한 승인된 generated-root ceremony가 필요합니다.
Secret payload는 Terraform resource/data source로 관리하지 않습니다.
Provider token과 PostgreSQL credential은 ephemeral variable과 write-only
argument를 통해 실행 시점에만 전달합니다. Vault init material, token,
password, plan과 state를 Git에 저장하지 않습니다.
기존 `vault-core`에서 세 state로 바꾸는 작업은 선언 이동과 state ownership
이관을 분리해 수행합니다. Source에서는 `removed { destroy = false }`,
destination에서는 import를 사용하고, 양쪽 plan의 destroy가 0인지 확인하기
전에는 apply하지 않습니다. Broad `platform-admin`/`vault-operator`와
미사용 Keycloak/PostgreSQL operator policy/role은 새 state로 옮기지
않으며 consumer가 없음을 확인한 별도 decommission에서 제거합니다.
-25
View File
@@ -1,25 +0,0 @@
# ADR 0003: Vault topology
Status: accepted for dev, production decision pending
동일한 단일 노드 K3s 안의 두 Vault는 failure domain을 분리하지 못하면서
초기화, Transit credential, rotation과 staged apply 절차를 추가했다.
따라서 `dev-k3s`는 단일 self-hosted Vault로 단순화한다.
Dev profile:
- single-node integrated Raft
- Shamir 1-of-1 init/unseal
- TLS 미적용
- 명시적 backup/recovery runbook
이 구성은 production에 사용할 수 없다. production은 다음 중 하나를
선택해야 한다.
- managed Vault
- workload cluster 밖의 독립 HA Vault
- 최소 3-node integrated-Raft + TLS + KMS/HSM auto-unseal + PDB,
anti-affinity와 정기 restore exercise
production Vault가 결정되기 전에는 production manifest와 Terraform root를
만들지 않는다.
@@ -1,44 +0,0 @@
# ADR 0004: Single Argo CD root and stage-gated ApplicationSets
Status: accepted
Updated: 2026-07-26
Argo CD 설치 후 bootstrap 전용 `gitops-control-plane` AppProject와 단일
root Application을 순서대로 수동 seed합니다. Root는
`gitops/clusters/dev-k3s`를 source로 사용합니다. 이 cluster root가
`gitops/platform/control-plane/argocd`의 AppProject와 ApplicationSet을 소유하고,
ApplicationSet이 platform addon/shared service, system, workload
Application을 생성합니다. Bootstrap Project는 canonical repository,
`argocd` namespace와 AppProject/ApplicationSet kind만 허용합니다.
반복 `kubectl apply`와 category별 root wrapper는 사용하지 않습니다.
Routine deployment는 Git merge만으로 시작합니다.
각 ApplicationSet inventory 항목은 다음 계약을 명시합니다.
- 고유 이름, AppProject, source, destination namespace
- component/cluster/path와 automated reconciliation 허용 여부인 quoted
string `autoSync`
새 항목과 외부 준비 조건이 있는 항목은 `autoSync: "false"`로 시작합니다.
현재 bootstrap은 Sealed Secrets와 Vault만 열린 상태에서 시작해
foundation/workloads state와 secret seed, injector, auth-system, database,
first-party workload 순서로 별도 PR gate를 엽니다. Template은
`autoSync: "true"`인 항목에만 automated sync, prune, self-heal을
생성합니다.
Gate가 닫힌 Application의 수동 sync도 change record와 명시적 operator
판단을 요구합니다.
Sync wave는 AppProject(`-10`)를 ApplicationSet(`-5`)보다 먼저 생성합니다.
모든 ApplicationSet은 같은 wave이며 element별 stage field는 없습니다.
서로 다른 generated Application의 readiness는 gate와 runbook이
제어합니다. Workload와 hook은 Vault/DB가 늦게 준비되는 상황을 retry할
수 있고 idempotent해야 합니다.
Root는 AppProject와 ApplicationSet만 prune 대상으로 봅니다. Generated
Application의 owner는 ApplicationSet이며 `create-update`에서는 element
제거만으로 삭제되지 않습니다. Application/resource 해체는 별도
decommission runbook과 확인 승인을 사용합니다. Shared resource 소유권
충돌은 sync를 실패시킵니다. Sync hook을 사용하는 Application에는
`ApplyOutOfSyncOnly=true`를 사용하지 않습니다.
-33
View File
@@ -1,33 +0,0 @@
# ADR 0005: Cluster-first repository layout
Status: accepted
Updated: 2026-07-26
현재는 단일 `dev-k3s`와 소수 workload를 다루므로 GitOps configuration
monorepo를 유지합니다. Application source repository와 deployment
configuration repository는 분리합니다. 이 저장소 자체는 독립 reference
lab이며 범용 platform product로 간주하지 않습니다.
- `gitops/platform`, `gitops/apps/systems`, `gitops/apps/workloads`:
ownership별 base; 환경 중립은 목표 contract
- `gitops/clusters/<cluster>`: GitOps controller가 읽는 cluster root
- `gitops/clusters/<cluster>/overlays`: cluster-specific final composition
- `gitops/platform/control-plane/argocd/projects`: Argo 권한 경계
- `gitops/platform/control-plane/argocd/application-sets`: reconciliation inventory
- `infrastructure`: Kubernetes manifest와 분리된 external API IaC
- `bootstrap`: controller가 존재하기 전의 최소 seed
`gitops/clusters`가 배포 가능한 최종 상태를 소유합니다. Argo CD는
catalog base를 직접 source로 사용하지 않습니다. `foundation`은 directory
taxonomy가 아니라 bootstrap ordering/stage이고, 구체적인 ownership 분류는
ADR 0007을 따릅니다.
현재 Keycloak base의 `start-dev`와 Vault base의
TLS-off/single-node identity는 이 contract를 위반하는 알려진 리팩터링
부채입니다. 다른 환경을 추가하기 전에 해당 값을 component overlay나
configuration input으로 분리합니다.
Production 접근권한, 소유 팀, Terraform backend 또는 release cadence가
실제로 갈라질 때 platform GitOps, workload GitOps, IaC repository 분리를
재검토합니다. 존재하지 않는 환경의 skeleton은 유지하지 않습니다.
-33
View File
@@ -1,33 +0,0 @@
# ADR 0006: Gateway API first, Istio deferred
Status: accepted
현재 단일 노드 K3s와 auth/api 중심 workload에는 service mesh 운영 비용을
정당화할 mTLS identity, L7 authorization, canary traffic policy 또는
multi-team 요구가 없다. 이번 개편에는 Istio를 설치하지 않는다.
선행 작업:
1. Traefik Gateway API provider와 GatewayClass 검증
2. Ingress를 Gateway/HTTPRoute로 이관
3. north-south TLS
4. 내부 호출의 ingress hairpin 제거
5. Vault/PostgreSQL native TLS
6. NetworkPolicy regression test와 observability/SLO
Istio 요구가 실제화되면 sidecar가 아니라 ambient mode로 제한 pilot한다.
초기 범위는 api-server와 auth-server이며 Vault, Vault injector,
PostgreSQL은 제외한다. ztunnel L4부터 시작하고 L7 정책이 필요할 때만
waypoint를 추가한다.
다음 기능 요구 중 두 개 이상과 운영 선행조건이 모두 충족될 때 ADR을
재검토한다.
- ServiceAccount identity 기반 east-west mTLS
- path/JWT 기반 L7 authorization
- canary traffic split/retry/timeout/outlier detection
- 지속적인 서비스·namespace·팀 증가
- application instrumentation만으로 해결하기 어려운 장애 분석
현재 Ingress를 즉시 제거하지 않는다. TLS, DNS, GatewayClass 계약이
확정되기 전 가상의 Gateway 설정을 배포하지 않기 위함이다.
@@ -1,65 +0,0 @@
# ADR 0007: Repository ownership boundaries
Status: accepted
Date: 2026-07-26
## Context
기존 layout은 Vault, PostgreSQL, Keycloak과 Project Auth 구성을 모두
`platform` 또는 `foundation`으로 표현했습니다. 이 이름은 설치 순서를
보여 주지만 누가 소비하고 변경을 책임지는지 구분하지 못했습니다.
클러스터별 최종 구성도 `manifests`라는 일반 이름 아래 섞여 있어 base와
overlay의 관계가 불명확했습니다.
이 저장소는 하나의 실제 사내 플랫폼을 배포하는 저장소가 아니라 Project
Auth를 예제로 한 독립 GitOps reference lab입니다. 따라서 존재하지 않는
팀/환경을 가정한 추상화보다 현재 리소스의 실제 owner와 lifecycle을
명확히 해야 합니다.
## Decision
최상위 Kubernetes desired state를 다음 소유권으로 분류합니다.
- `gitops/platform`: 여러 system이 사용할 수 있고 독립 lifecycle을 가진
cluster capability
- `gitops/apps/systems`: 특정 bounded context가 소유하는 backing services와
domain configuration
- `gitops/apps/workloads`: 별도 source repository와 release digest를 가진
first-party 실행 애플리케이션
- `gitops/clusters/<cluster>/overlays`: 위 base에 namespace, image, host,
secret reference, network boundary를 결합한 최종 구성
Vault는 `gitops/platform/shared-services/vault`에 둡니다. Sealed Secrets와 Vault
Agent Injector는 cluster addon inventory로 관리합니다. PostgreSQL,
Keycloak, realm/client sync는 Project Auth 전용이므로
`gitops/apps/systems/auth-system`으로 이동합니다. `auth-server`와
`api-server`는 `gitops/apps/workloads`에 유지합니다.
Project Auth backing system의 namespace는 `auth-system-dev`로 정하고,
Vault KV 경로도 `systems/auth-system` 또는 실제 workload owner를
반영하도록 바꿉니다.
`foundation`은 ownership directory로 사용하지 않습니다. 준비 순서는
분리된 ApplicationSet category, 명시적 `autoSync` gate, runbook과 workload
retry/idempotency로 표현합니다.
## Consequences
- 디렉터리 경로만 보고 owner와 blast radius를 추론할 수 있습니다.
- Base는 환경 중립 contract를 목표로 하고 Argo CD는 cluster overlay만
source로 사용합니다. 현재 Keycloak/Vault base의 dev-only 값은 알려진
후속 리팩터링 대상입니다.
- auth-system 이동은 namespace, DNS, NetworkPolicy, Vault policy/path와
Terraform role binding을 함께 바꾸는 migration입니다. 단순 파일 이동으로
취급하면 안 됩니다.
- ApplicationSet 도입은 반복 YAML을 줄이지만 각 파일에 project를 고정하고
Git 항목에는 component, cluster, destination, path와 quoted `autoSync`를
명시하도록 요구합니다. Git revision은 template의 `main`으로 고정합니다.
- 새 capability가 공용인지 system 전용인지 애매하면 소비자 수, owner,
release cadence가 분리되는지를 먼저 검토합니다.
- 실제 production 요구가 생기기 전에는 production skeleton을 만들지
않습니다.
세부 path와 예시는
`docs/architecture/repository-taxonomy.md`를 따른다.
@@ -1,45 +0,0 @@
# ADR 0008: Adopt the Kubernetes template lifecycle layout
Status: accepted
Date: 2026-07-26
## Context
기존 저장소는 `clusters`, `platform`, `systems`, `workloads`, `iac/terraform`,
`policies`와 `hack`을 각각 최상위에 두었습니다. 리소스 소유권은 구분했지만
bootstrap, infrastructure, GitOps desired state의 수명주기 경계가 저장소
최상위에서 일관되게 드러나지 않았습니다.
## Decision
`k8s-template`의 수명주기 구조를 canonical repository layout으로 채택합니다.
- Argo CD 최초 seed는 `bootstrap/gitops/argocd`에 둡니다.
- Vault Terraform component와 실행 root는 각각
`infrastructure/components`와 `infrastructure/live`에 둡니다.
- Kubernetes desired state는 `gitops/platform`, `gitops/apps`,
`gitops/clusters` 아래에만 둡니다.
- 기존 system/workload 소유권 분류는 `gitops/apps/systems`와
`gitops/apps/workloads` 하위에서 유지합니다.
- 환경별 Vault ACL은 이를 소비하는 `infrastructure/live` state root의
`policies`에 함께 둡니다. Kubernetes admission 정책용
`gitops/policies`와 혼합하지 않습니다.
- `gitops/clusters/dev-k3s`를 Argo CD bootstrap root의 유일한 source로
사용하고, 이 root가 permission-scoped ApplicationSet control plane을
조립합니다.
- 공통 `_template`, 예제, 구조/보안 검증을 유지하고 프로젝트별 검증을 그
위에 추가합니다.
## Consequences
- 최상위 경로만으로 bootstrap, infrastructure, GitOps lifecycle을 구분할
수 있습니다.
- 기존 AppProject, ApplicationSet, `autoSync` gate와 세 Vault state의
소유권은 유지됩니다.
- backend 예시는 각 live root에, Vault ACL은 소비 state에 가까이 위치합니다.
- Argo CD source path와 Terraform module source가 변경되므로 이미 연결된
live 시스템의 이관은 별도 diff, orphan/prune 검토와 승인 없이 실행하지
않습니다.
- 이 ADR의 구현은 Git 작업 트리에서만 수행하며 live cluster, Vault,
Terraform backend를 변경하지 않습니다.
-26
View File
@@ -1,26 +0,0 @@
# Architecture Decision Records
프로젝트의 장기 구조에 영향을 주는 선택은 ADR로 남깁니다.
파일명은 `NNNN-kebab-case-title.md`를 사용하고 다음 형식을 따릅니다.
```markdown
# NNNN. 제목
- 상태: 제안 | 승인 | 폐기 | 대체
- 날짜: YYYY-MM-DD
- 결정자: 팀 또는 역할
## 배경
## 결정
## 결과
## 대안
```
기존 결정을 바꿀 때 문서를 지우지 말고 새 ADR에서 이전 ADR을 대체했다고
표시합니다.
현재 프로젝트 결정은 이 디렉터리의 `0001`부터 순서대로 관리합니다.
-146
View File
@@ -1,146 +0,0 @@
# Getting Started
이 문서는 이 저장소가 채택한 공통 템플릿 구조와 새 catalog 항목 생성 규칙을
설명합니다. Project GitOps의 실제 입문 순서와 운영 gate는
[`intern-guide.md`](intern-guide.md)와 runbook을 우선합니다.
## 예제를 먼저 확인하기
실제 파일을 만들기 전에 두 예제를 설계 참고 자료로 사용합니다.
1. `examples/minimal`에서 단일 환경의 canonical 폴더와 조립 방식을 확인합니다.
2. 다음 명령으로 platform과 app이 cluster root에서 합쳐지는 결과를 확인합니다.
```bash
kubectl kustomize examples/minimal/gitops/clusters/dev/main
```
3. 다중 계정·리전·클러스터가 필요하면 `examples/scaled/README.md`에서 경로와
state 분리 기준을 선택합니다.
4. 실제 파일은 `examples`에서 복사하지 않고 각 책임 폴더의 `_template`에서
생성합니다.
```text
examples ──▶ 구조 선택 ──▶ _template 복사 ──▶ live/clusters 구현
```
## 1. 프로젝트 선택 기록
구현을 추가하기 전에 다음 항목을 결정하고 `docs/decisions`에 ADR을 작성합니다.
- cloud/on-prem provider와 account/project 구조
- Terraform, OpenTofu, Pulumi 등 IaC 엔진
- Kustomize 중심 또는 Helm 사용 범위
- Flux 또는 Argo CD 등 GitOps 컨트롤러
- External Secrets 또는 SOPS 등 비밀 관리 방식
- admission policy와 observability 운영 범위
선택하지 않은 도구의 빈 폴더를 모두 만들 필요는 없습니다.
Terraform/OpenTofu를 선택했다면 IaC 파일을 추가하기 전에 다음 선택 파일을
만들고 한 값만 활성화합니다.
```bash
cp infrastructure/.iac-engine.example infrastructure/.iac-engine
```
`.iac-engine`에는 주석을 제외하고 `tofu` 또는 `terraform` 한 줄만 남깁니다.
선택한 도구와 version을 CI에도 설치·고정하고 project-specific
`init -backend=false`/`validate` 검사를 추가합니다.
## 2. 프로젝트 메타데이터 설정
1. `README.md`의 제목과 프로젝트 범위를 바꿉니다.
2. `.github/CODEOWNERS.example`을 실제 소유자로 수정한 뒤 `CODEOWNERS`로
이름을 바꿉니다.
3. `SECURITY.md`에 조직의 보안 연락처와 SLA를 추가합니다.
4. 선택한 도구 버전을 프로젝트의 버전 관리 방식으로 고정합니다.
5. branch protection과 required check를 설정합니다.
## 3. Foundation bootstrap
`bootstrap/foundation` 아래에 remote state, locking, 초기 CI identity 등
다른 인프라가 의존하는 최소 구성을 작성합니다.
Foundation은 일반 infrastructure state와 분리하고 변경 권한을 좁게 유지합니다.
이미 조직 공통 foundation이 있다면 이 폴더에는 외부 의존 계약과 초기화 방법만
문서화해도 됩니다.
## 4. Infrastructure 작성
작은 프로젝트는 component와 live root만으로 시작합니다.
```bash
cp -R infrastructure/components/_template infrastructure/components/kubernetes-cluster
mkdir -p infrastructure/live/dev
cp -R infrastructure/live/_template infrastructure/live/dev/cluster
```
동일한 조합이 여러 환경에서 반복될 때만 stack을 추가합니다.
```bash
cp -R infrastructure/stacks/_template infrastructure/stacks/cluster
```
`live` root마다 backend/state를 분리하고, provider credential은 파일에 저장하지
않습니다.
## 5. Desired state 조립
필요한 catalog 템플릿을 복사합니다.
```bash
cp -R gitops/platform/_template gitops/platform/core
cp -R gitops/apps/_template gitops/apps/example-api
mkdir -p gitops/clusters/dev
cp -R gitops/clusters/_template gitops/clusters/dev/main
```
component의 `base`에 공통값을 두고, 환경 차이가 있을 때만 overlay를 추가합니다.
마지막으로 cluster `kustomization.yaml`이 사용할 component를 참조하게 합니다.
복사된 README의 `__REPLACE_ME_*__` 값을 모두 실제 메타데이터로 바꿉니다.
controller에 연결하기 전에 실제 cluster root를 로컬에서 렌더해 확인합니다.
## 6. GitOps bootstrap
desired-state root가 준비되고 클러스터가 생성되면 `bootstrap/gitops`에서 GitOps
컨트롤러 하나를 선택해 설치합니다. 이 단계에는 다음만 포함합니다.
- controller 설치 또는 설치 선언
- repository/OCI source 연결
- 검증된 `gitops/clusters/<...>` root reconcile 연결
- controller가 secret manager에 접근하는 최소 identity
일반 platform addon과 application은 이 단계에 넣지 않습니다.
## 7. 검증
```bash
make doctor
make check
kubectl kustomize examples/minimal/gitops/clusters/dev/main
kubectl kustomize gitops/clusters/dev/main
```
프로젝트에서 실제 IaC, Helm, policy 파일을 추가하면 필요한 validator를
`scripts/validate.sh`에 명시적으로 추가하고 CI에서도 같은 `make check`를
호출합니다. 도구가 없을 때 조용히 성공하도록 만들지 않습니다.
첫 환경은 다음 조건을 모두 만족하면 완료된 것으로 봅니다.
- 실제 `live` root의 대상, state, owner와 실행 절차가 작성되어 있다.
- 실제 cluster root가 필요한 catalog base/overlay를 참조하고 비어 있지 않다.
- cluster root 렌더 결과와 IaC plan이 리뷰 가능하다.
- GitOps bootstrap root가 `_template`이 아닌 실제 cluster root를 가리킨다.
- 비밀 관리, rollback과 담당자 연락 경로가 문서화되어 있다.
## 8. 운영 준비
- production apply 승인 및 concurrency lock
- backup/restore와 disaster recovery runbook
- cluster와 addon upgrade 정책
- secret rotation과 접근 감사
- alert routing과 담당자
- 비용, 용량, SLO 기준
운영 준비가 끝나기 전에는 예제 값을 production에 재사용하지 않습니다.
-117
View File
@@ -1,117 +0,0 @@
# Intern guide
## 이 저장소의 역할
이 저장소는 Project Auth를 예제로 한 독립 GitOps reference lab입니다.
애플리케이션 소스나 범용 production platform이 아닙니다. 현재 지원하는
환경은 `dev-k3s` 하나입니다.
서로 다른 세 reconciliation 경계를 먼저 구분합니다.
1. Gitea `main`이 승인된 desired-state revision을 저장합니다.
2. Argo CD가 그 revision의 Kubernetes 리소스를 지속적으로 맞춥니다.
3. Terraform이 승인된 실행 환경에서 Vault API 객체를 관리합니다.
GHCR은 빌드된 image를 보관할 뿐 desired-state source가 아닙니다. Argo
CD가 Terraform을 실행하지 않으며 CI가 routine deployment를 위해
`kubectl apply`를 호출하지 않습니다. Secret 값도 Git이나 Terraform을
통과하지 않습니다.
## 디렉터리를 고르는 법
- 여러 system이 공유하는 cluster capability: `gitops/platform`
- Project Auth bounded context 전용 backing service:
`gitops/apps/systems/auth-system`
- 별도 source repository에서 빌드하는 서버: `gitops/apps/workloads`
- Dev namespace, digest, host, Vault annotation: `gitops/clusters/dev-k3s/overlays`
- Vault API 객체: `infrastructure/components`와 `infrastructure/live`
현재 Vault는 platform shared service, PostgreSQL과 Keycloak은 auth-system,
`auth-server`와 `api-server`는 workload입니다. 설치 순서나 중요도로
`foundation`을 만들지 않습니다. 자세한 기준은
`docs/architecture/repository-taxonomy.md`에 있습니다.
## 안전한 변경 흐름
1. `refactor/...`, `feat/...`, `fix/...` branch에서 변경합니다.
2. `make validate`를 실행합니다.
3. Rendered manifest 또는 Terraform plan을 검토합니다.
4. 내부 Gitea에 PR을 생성합니다.
5. 승인 후 `main`에 merge합니다.
6. Kubernetes 변경은 열린 `autoSync` gate에서 Argo CD가 반영합니다.
7. Terraform 변경은 해당 state identity로 별도 승인 후 실행합니다.
새 ApplicationSet element는 기본적으로 `autoSync: "false"`로 추가합니다.
선행 controller, Vault 구성, secret과 database 준비를 확인한 별도 PR에서
gate를 엽니다. Gate가 닫혀도 수동 Sync는 가능하므로 임의로 누르지
않습니다.
금지 사항:
- `.terraform`, state, plan, tfvars, Vault init JSON, token commit
- 동일 Vault path/resource를 두 state에서 관리
- Secret payload를 Terraform resource/data source로 관리
- Image promotion workflow의 `main` 직접 push
- Routine CI 또는 사람의 직접 `kubectl apply`
- Production skeleton이나 이름뿐인 production Application 추가
- Hook을 사용하는 Application에 `ApplyOutOfSyncOnly=true` 적용
- `autoSync: "true"` 전환 PR에서 누적 live diff를 확인하지 않음
## 자주 쓰는 읽기 전용 명령
최종 dev manifest 렌더링:
```bash
kubectl kustomize gitops/clusters/dev-k3s/overlays/workloads/auth-server
kubectl kustomize gitops/clusters/dev-k3s/overlays/systems/auth-system
kubectl kustomize gitops/clusters/dev-k3s/overlays/platform/vault
```
전체 정적 검증:
```bash
make validate
```
Backend 없이 Terraform configuration 검증:
```bash
for terraform_root in vault-foundation vault-workloads vault-database; do
terraform_data_dir="$(mktemp -d)"
TF_DATA_DIR="$terraform_data_dir" \
terraform -chdir="infrastructure/live/dev-k3s/${terraform_root}" \
init -backend=false -input=false -lockfile=readonly
TF_DATA_DIR="$terraform_data_dir" \
terraform -chdir="infrastructure/live/dev-k3s/${terraform_root}" validate
rm -rf "$terraform_data_dir"
done
```
일반적으로는 같은 검사를 포함한 `make validate`를 사용합니다. 위 예는
provider data를 repository의 `.terraform`에 남기지 않습니다.
실제 plan은 승인된 backend와 identity를 준비한 뒤 수행합니다.
```bash
make terraform-plan \
TF_ROOT=vault-workloads \
BACKEND_CONFIG=.local/terraform-backend/dev-k3s/vault-workloads.s3.hcl
```
Image 승격은 Gitea `Promote Dev Image by Pull Request` workflow에 정확한
`sha256:` digest를 전달합니다. Workflow는 전용 branch와 PR을 만들며
`main`에 직접 쓰지 않습니다.
## 읽는 순서
1. `README.md`
2. `docs/architecture/repository-taxonomy.md`
3. `docs/architecture/deployment.md`
4. `docs/architecture/argocd.md`
5. `docs/architecture/secret-trust.md`
6. `docs/architecture/terraform.md`
7. `docs/decisions/`
8. 수행하려는 작업의 runbook
2026-07-26 리팩터링은 repository에서만 구현·검증했으며 실제 cluster에
적용하지 않았습니다. Live migration을 연습 과제로 실행하지 않습니다.
-1
View File
@@ -219,7 +219,6 @@ done
if rg -n \
'github\\.com/DongHyeonka/Project-Auth-GitOps|bitnami-labs\\.github\\.io/sealed-secrets|/home/donghyeon/dev/Project-Auth-GitOps|terraform/vault(-transit)?/(dev|reconcile)|gitops/clusters/dev-k3s/manifests|platform/auth-system|platform/security/vault|platform-config|postgres\\.platform\\.svc|keycloak(-public)?\\.platform\\.svc|kv/data/dev/platform' \
--glob '!docs/archive/**' \
--glob '!docs/runbooks/terraform-state-migration.md' \
--glob '!scripts/project-validate.sh' \
.; then
-2
View File
@@ -33,8 +33,6 @@ required_directories=(
gitops/policies/_template
gitops/tenants/_template
gitops/apps/_template
docs/architecture
docs/decisions
docs/runbooks
examples/minimal
scripts