AKS에서의 클라우드 딜리버리
개요
Kubernetes/Azure를 위한 배포 메커니즘입니다. AKS에서 배포 안전성과 검증 게이트를 구현합니다. 스택별로 설계되어 이 스킬은 작업에 k8s/AKS가 포함된 경우에만 로드되므로, 클라우드 배포가 없는 프로젝트(예: 로컬 전용 Docker Compose)에서는 이 콘텐츠가 표시되지 않습니다.
배포 규칙
- 로컬 개발은 전체 스택을 실행합니다. Docker Compose를 사용하며, 하나의 명령어로 포괄적으로 실행됩니다 — 최우선 요구사항입니다.
- CI에서 이미지를 빌드 → GHCR에 콘텐츠 다이제스트로 식별한 후, 변경 없이 프로모션합니다(미리보기 → 스테이징 → 프로덕션). 환경별로 다시 빌드하지 않습니다.
- PR별 임시 미리보기 환경. 각 PR은 AKS의 자체 격리된 네임스페이스에 배포되어 검토를 받고, 병합 또는 종료 시 제거됩니다. 통합 테스트 베드이며, 생성 및 삭제 비용이 저렴합니다.
- Kubernetes 상태 게이팅. 모든 워크로드는 liveness, readiness, startup 프로브(
observability-and-slos의 엔드포인트에 연결됨), 제한된maxUnavailable/maxSurge가 있는 롤링 업데이트 전략, PodDisruptionBudget을 정의합니다. 부하 분산을 위해 HPA를 사용합니다. - 프로덕션으로의 점진적 딜리버리. Argo Rollouts / Flagger를 통한 카나리 또는 블루-그린으로, SLO와 연계된 자동화된 메트릭 분석을 수행합니다. 실패한 카나리는 자동으로 중단됩니다.
- 롤백은 최우선 사항이며 사전 연습됩니다. 불변의 다이제스트 주소 이미지는 롤백을 이전에 정상이었던 다이제스트를 재배포하는 방식으로 만듭니다(
kubectl rollout undo/ rollout 중단). 위험한 변경 사항을 배포하기 전에 검증됩니다. - 마이그레이션은 별도의 순서가 있는 파이프라인 단계로, 확장 안전하며(
zero-downtime-migrations참조), 의존하는 코드보다 먼저 실행됩니다. 새 스키마가 필요한 파드에 절대 포함되지 않습니다. - CI가 게이트입니다: lint, 타입체크, 계약 검사, 테스트, 보안 스캔이 모든 변경 사항에 대해 실행되고,
enforced모드에서는 병합을 차단합니다. CI는 이미지를 빌드하고 출처 증명을 게시한 다음, 해당 다이제스트를 변경 없이 프로모션합니다. - 개발/프로덕션 동등성 및 환경으로부터의 설정. Azure Key Vault의 시크릿(Secrets Store CSI 드라이버 또는 sealed secrets 통해) — 이미지나 커밋된
.env파일에는 절대 없습니다. 포트/설정은 환경 변수에서 가져옵니다. 개발 전용 도구(pgTAP, 테스트 러너)는 프로덕션 이미지에 절대 포함되지 않습니다.
파이프라인
| 계층 | 트리거 | 환경 | 다이제스트 |
|---|---|---|---|
| preview | PR 열림 / 동기화 | 임시 ns preview-<app>-pr-<N> | 여기서 빌드, 태그 sha-<pr-head> |
| staging | main에 병합 | 영구 ns staging | preview 다이제스트를 리태그하여 sha-<merge> |
| production | 릴리스 게시 + 승인 | ns production | 릴리스 커밋의 부모 다이제스트 |
부모 커밋을 사용하는 이유. release-please의 릴리스 커밋은 CHANGELOG.md와 매니페스트만 변경하므로, 해당 트리는 스테이징에서 검증된 트리가 아닙니다. 릴리스 PR 자체를 위해 preview가 빌드한 것은 preview를 넘어 프로모션된 적이 없습니다. 부모는 마지막 기능 병합이며, 이는 release-please가 릴리스 브랜치를 main의 최신 상태로 유지하는 한(기본 동작) 스테이징이 검증해온 것과 정확히 일치합니다. 실시간 클러스터 상태가 아닌 git에서 다이제스트를 파생하면 프로모션이 재현 가능합니다.
리태그 안전성. 스쿼시 병합은 다른 커밋 SHA를 생성하고, main이 PR이 열려 있는 동안 이동했다면 다른 트리를 생성합니다. 두 가지 보호 장치가 있습니다:
- "병합 전 브랜치 업데이트" 요구 — 필수 상태 검사 규칙의 하위 집합 — 스쿼시 트리가 PR 헤드 트리와 같도록 보장합니다. 이 보호 장치는 브랜치 보호가 필요하므로
enforced모드에서만 존재합니다.advisory모드의 프로젝트는 아래 트리 비교만 유일한 보호 장치로 사용하며, 재빌드 경로가 예외적이 아닌 일상적인 것으로 예상해야 합니다. - 가정하지 말고 검증합니다:
git rev-parse <merge>^{tree}를 PR 헤드 트리와 비교합니다. 동일 → 리태그. 다름 → 병합 SHA에서 재빌드. 이는 배포 규칙이 금지하는 환경별 재빌드가 아닙니다. 트리가 다르다는 것은 콘텐츠 자체가 preview에서 검증된 것과 다르다는 의미이므로, 프로모션 가능한 아티팩트가 없습니다 — 재빌드된 이미지는 프로모션이 아닌 새로운 후보로 스테이징에 진입합니다. 이 경로를 사용할 때 포기하는 점을 유의하십시오: 해당 이미지는 preview 환경에서 검토된 적이 없으므로 "배포된 이미지가 검토된 이미지다"는 성립하지 않습니다. 스테이징은 두 번째 검증이 아닌 첫 번째 검증이 됩니다.
리태그는 포인터 작업입니다 — 재빌드나 풀이 필요 없습니다:
docker buildx imagetools create -t "$REPO:sha-$MERGE_SHA" "$REPO@sha256:$DIGEST"
증명은 PR 헤드 SHA에 바인딩된 상태로 유지되므로, 배포 레코드에 헤드→병합 매핑을 기록하십시오. 이미지 구성은 재빌드 없이 편집할 수 없습니다.
승인 게이트 — 하나의 속성, 두 가지 메커니즘:
| 모드 | 메커니즘 |
|---|---|
enforced | 필수 리뷰어가 있는 GitHub 환경 production |
advisory | workflow_dispatch 프로모트 작업; 이를 실행하는 것이 결정입니다 |
빠른 참조
| 관심사 | 메커니즘 |
|---|---|
| 시크릿 | Key Vault → CSI 드라이버; 교체됨; 이미지에 절대 없음 |
| 상태 | liveness + readiness + startup 프로브; readiness는 실제 의존성 확인 |
| 안전한 롤아웃 | 카나리/블루-그린, SLO 게이트, 실패 시 자동 중단 |
| 롤백 | 이전에 정상이었던 다이제스트를 재배포; 위험한 배포 전에 연습 |
| PR별 환경 | 격리된 네임스페이스, 병합 시 제거 |
| 스키마 | 별도의 순서 단계, 확장 안전, 코드보다 먼저 |
| 프로모션 | 다이제스트 리태그; 환경별로 절대 재빌드하지 않음 |
| 승인 | 환경 리뷰어(enforced) 또는 수동 디스패치(advisory) |
이것이 격리된 이유: 모든 Azure/k8s 특정 사항이 스택별 트리거 뒤에 여기에 있습니다. 로컬 전용 또는 다른 클라우드 프로젝트는 자체 배포 스킬로 대체합니다. 원칙(불변 아티팩트, 되돌릴 수 있는 + 점진적 배포, 분리된 마이그레이션)은 resilience-and-deploy-safety에서 비롯됩니다.
전체 근거: 헌법 제XIX조, engineering-constitution/references/engineering-constitution.md에 번들로 제공됩니다.