project-gitops/INTERN_GUIDE.md

Intern Guide

먼저 이해할 것

이 저장소에는 서로 다른 세 개의 reconciliation 경계가 있습니다.

1. Gitea가 승인된 desired-state revision을 저장합니다.
2. Argo CD가 그 revision의 Kubernetes 리소스를 지속적으로 맞춥니다.
3. Terraform이 승인된 실행 환경에서 Vault API 객체를 관리합니다.

Argo CD가 Terraform을 실행하지 않으며 CI가 routine deployment를 위해 kubectl apply를 호출하지 않습니다. secret 값도 Git이나 Terraform을 통과하지 않습니다.

안전한 변경 흐름

1. refactor/..., feat/..., fix/... 브랜치에서 변경합니다.
2. make validate를 실행합니다.
3. rendered manifest 또는 Terraform plan을 검토합니다.
4. 내부 Gitea에 PR을 생성합니다.
5. 승인 후 main에 merge합니다.
6. Kubernetes 변경은 Argo CD가 자동 반영합니다.
7. Terraform 변경은 별도 승인 후 실행합니다.

금지 사항:

• .terraform, state, plan, tfvars, Vault init JSON, token commit
• 동일 Vault path/resource를 두 state에서 관리
• image promotion 자동화의 main 직접 push
• routine CI의 직접 kubectl apply
• production skeleton이나 이름뿐인 production Application 추가
• hook을 사용하는 Application에 ApplyOutOfSyncOnly=true 적용

자주 쓰는 명령

최종 dev manifest 렌더링:

kubectl kustomize clusters/dev-k3s/manifests/auth-server
kubectl kustomize clusters/dev-k3s/manifests/auth-system

전체 검증:

make validate

backend 없이 Terraform configuration 검증:

terraform -chdir=iac/terraform/live/dev-k3s/vault-core init -backend=false
terraform -chdir=iac/terraform/live/dev-k3s/vault-core validate

실제 plan:

make terraform-plan \
  TF_ROOT=vault-core \
  BACKEND_CONFIG=.local/terraform-backend/dev-k3s/vault-core.s3.hcl

image 승격은 Gitea Promote Dev Image by Pull Request workflow에 정확한 sha256: digest를 전달합니다. workflow는 전용 브랜치와 PR을 만들며 main에 직접 쓰지 않습니다.

읽는 순서

1. README.md
2. docs/architecture/deployment.md
3. docs/architecture/secret-trust.md
4. docs/adr/
5. 수행하려는 작업의 runbook