배포 가이드¶

현재 저장소가 직접 정의하는 배포 자산은 cloudbuild.yaml, .github/workflows/onprem-cd.yml과 deploy/ Helm Chart입니다. 두 delivery pipeline 모두 image와 GitOps desired state까지만 갱신하며 Kubernetes API를 직접 호출하지 않습니다.

flowchart LR
    PUSH["Source push"] --> BUILD["Build image"]
    BUILD --> REG["Artifact Registry"]
    BUILD --> TAG["Update desired image tag"]
    TAG --> ARGO["Argo CD"]
    ARGO --> HELM["Render deploy/ Chart"]
    HELM --> K8S["Kubernetes"]

현재 계약¶

환경	현재 저장소의 trigger	desired-state 갱신	클러스터 반영
GCP development	외부 Cloud Build trigger가 `develop`에서 `cloudbuild.yaml` 실행	`deploy/values-dev.yaml` 자동 commit	외부 Argo CD Application 설정
GCP production	재사용 가능한 Cloud Build 구성만 존재	trigger가 주입한 `_VALUES_FILE` 갱신	외부 Argo CD Application 설정
On-premises	`develop` push 또는 수동 `CD (on-prem)`	`mago-onprem-infra/main`의 서비스 `image.yaml` 직접 commit	workflow 메시지 기준 관리자 Argo CD sync

현재 저장소에는 GCP용 .github/workflows/cd.yml이 없습니다. Production Cloud Build trigger와 GCP Argo CD sync policy도 이 저장소에서 생성하지 않으므로 존재하거나 활성화되어 있다고 보장할 수 없습니다. 인프라 저장소와 실제 Cloud Build/Argo CD 설정을 함께 확인해야 합니다.

Chart 계약¶

환경별 values:

deploy/values-dev.yaml: GCP development
deploy/values-prd.yaml: GCP production
deploy/values-onprem.yaml: on-prem runtime overlay
on-prem image tag: 외부 mago-onprem-infra/gitops/apps/values/sohri-graph-builder-onprem/image.yaml

주요 template은 Deployment, Service, ConfigMap, ServiceAccount, ExternalSecret, Ingress, HPA, PDB와 validation입니다. ConfigMap checksum과 선택적 Stakater Reloader annotation을 렌더링합니다.

강제되는 제한¶

sessionStorage.mode는 memory만 허용합니다.
replicaCount는 1보다 클 수 없습니다.
HPA를 켜더라도 maxReplicas는 1보다 클 수 없습니다.
기본·환경별 values에서는 HPA와 PDB가 비활성입니다.
GCP ExternalSecret은 External Secrets Operator와 GKE Workload Identity를 전제로 합니다.
On-prem은 기존 runtime Secret과 image pull Secret을 전제로 하며 ExternalSecret과 NEG를 끕니다.

알려진 검증 불일치¶

dm/tests/test_deploy_contract.py의 on-prem workflow 검사는 현재 실제 workflow와 일치하지 않습니다. 테스트는 존재하지 않는 deploy/values-onprem-image.yaml과 서비스 저장소 branch 갱신 방식을 기대하지만, 실제 workflow는 mago-onprem-infra/main의 중앙 image.yaml을 갱신합니다. 이 불일치가 해소되기 전에는 해당 테스트를 배포 절차의 source of truth로 사용하지 말고 workflow 실행 내용과 Argo CD diff를 직접 확인합니다.

문서¶

설명이 충돌하면 실제 workflow와 deploy/templates//values, 외부 Argo CD Application, 이 문서 순으로 확인합니다.