GCP 배포¶

GCP용 저장소 계약은 cloudbuild.yaml과 GCP values/Helm manifest입니다. Cloud Build trigger, GKE cluster, load balancer와 Argo CD Application은 외부 인프라에서 관리하므로 이 저장소만으로 활성 상태를 보장하지 않습니다.

sequenceDiagram
    participant Trigger as External Cloud Build trigger
    participant Build as cloudbuild.yaml
    participant Registry as Artifact Registry
    participant Repo as GitHub
    participant Argo as External Argo CD
    Trigger->>Build: branch와 substitutions 전달
    Build->>Build: ruff E9 + compileall
    Build->>Registry: SHORT_SHA와 latest push
    Build->>Repo: _VALUES_FILE image.tag commit
    Argo->>Repo: desired state 읽기
    Argo->>Argo: 정책에 따라 sync

환경 values¶

항목	Development	Production
예상 branch	`develop`	`main`
Values	`deploy/values-dev.yaml`	`deploy/values-prd.yaml`
Project	`sohri-dev`	`sohri-prd`
Cluster	`sohri-dev-gke`	`sohri-prd-gke`
Region	`asia-northeast3`	`asia-northeast3`
Image repository	`sohri-dev-docker/sohri-graph-builder`	`sohri-prd-docker/sohri-graph-builder`

values-prd.yaml은 현재 image.tag: latest입니다. productionValidation은 비어 있는 필수값을 막지만 mutable tag를 금지하지 않으므로, production rollout 전에 delivery pipeline이 immutable commit SHA로 바꿨는지 확인해야 합니다.

Cloud Build 입력과 동작¶

필수 substitutions:

_AR_REPOSITORY_URL
_IMAGE_NAME
_VALUES_FILE
_ENV_NAME
_GITHUB_REPO_SLUG
_GITHUB_PUSH_TOKEN_SECRET_VERSION

빌드는 image를 만든 뒤 SHORT_SHA와 latest를 push하고 _VALUES_FILE의 image.tag를 SHORT_SHA로 바꿔 같은 source branch에 push합니다. 동시 build의 non-fast-forward를 최대 5회 재시도하며 마지막 성공 writer의 tag가 남습니다. Kubernetes API는 호출하지 않습니다.

현재 주석과 저장소 상태가 보장하는 것은 development trigger가 외부 인프라에 정의되었다는 설계뿐입니다. Production trigger는 현재 구성에서 생성되지 않는다고 명시되어 있으며, 저장소에는 대체 GCP GitHub Actions workflow도 없습니다. cloudbuild.yaml 주석은 GCP Argo CD Application의 auto sync와 self-heal을 전제로 하지만 Application manifest는 이 저장소에 없으므로 실제 설정을 확인해야 합니다.

Runtime manifest¶

flowchart LR
    LB["External load balancer"] --> NEG["Standalone NEG"]
    NEG --> SVC["ClusterIP :59212"]
    SVC --> POD["FastAPI Pod"]
    KSA["Kubernetes ServiceAccount"] -. "GKE Workload Identity" .-> GSA["Google Service Account"]
    ESO["External Secrets Operator"] --> SM["Secret Manager"]
    ESO --> SECRET["Kubernetes Secret"]
    SECRET --> POD

Service는 values의 NEG 이름으로 standalone NEG annotation을 렌더링합니다.
ServiceAccount에는 iam.gke.io/gcp-service-account annotation을 붙입니다.
SecretStore/ExternalSecret이 OPENAI_API_KEY를 동기화합니다.
Deployment는 동기화된 Secret을 environment variable로 읽습니다.
Secret 변경 rollout은 cluster에 Stakater Reloader가 설치된 경우에만 발생합니다.

배포 전 확인¶

[ ] 실제 trigger branch와 substitutions
[ ] Artifact Registry push와 GitHub push 권한
[ ] production image tag가 immutable SHA인지
[ ] Project, cluster, GSA, Secret과 NEG가 인프라 output과 일치하는지
[ ] ESO, Workload Identity와 선택적 Reloader 설치 여부
[ ] Argo CD source path, values 파일과 sync policy
[ ] replica 1과 HPA 비활성