118 lines
4.6 KiB
Markdown
118 lines
4.6 KiB
Markdown
# 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을 연습 과제로 실행하지 않습니다.
|