refactor: Readme 수정 및 불필요한 문서 정리
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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` 진입점은 제공하지 않습니다.
|
||||
@@ -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)에 있다.
|
||||
|
||||
@@ -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는 이 리팩터링 리뷰 범위에 포함되지 않습니다.
|
||||
@@ -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로
|
||||
교체합니다.
|
||||
@@ -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/)
|
||||
@@ -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에 먼저
|
||||
기록합니다.
|
||||
@@ -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에서 허용되지 않습니다.
|
||||
@@ -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)
|
||||
@@ -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
@@ -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에서 제거합니다.
|
||||
@@ -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`를 사용하지 않습니다.
|
||||
@@ -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은 유지하지 않습니다.
|
||||
@@ -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를 변경하지 않습니다.
|
||||
@@ -1,26 +0,0 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
프로젝트의 장기 구조에 영향을 주는 선택은 ADR로 남깁니다.
|
||||
|
||||
파일명은 `NNNN-kebab-case-title.md`를 사용하고 다음 형식을 따릅니다.
|
||||
|
||||
```markdown
|
||||
# NNNN. 제목
|
||||
|
||||
- 상태: 제안 | 승인 | 폐기 | 대체
|
||||
- 날짜: YYYY-MM-DD
|
||||
- 결정자: 팀 또는 역할
|
||||
|
||||
## 배경
|
||||
|
||||
## 결정
|
||||
|
||||
## 결과
|
||||
|
||||
## 대안
|
||||
```
|
||||
|
||||
기존 결정을 바꿀 때 문서를 지우지 말고 새 ADR에서 이전 ADR을 대체했다고
|
||||
표시합니다.
|
||||
|
||||
현재 프로젝트 결정은 이 디렉터리의 `0001`부터 순서대로 관리합니다.
|
||||
@@ -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에 재사용하지 않습니다.
|
||||
@@ -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을 연습 과제로 실행하지 않습니다.
|
||||
@@ -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
|
||||
|
||||
@@ -33,8 +33,6 @@ required_directories=(
|
||||
gitops/policies/_template
|
||||
gitops/tenants/_template
|
||||
gitops/apps/_template
|
||||
docs/architecture
|
||||
docs/decisions
|
||||
docs/runbooks
|
||||
examples/minimal
|
||||
scripts
|
||||
|
||||
Reference in New Issue
Block a user