배포 가이드¶

sohri-graph-builder는 Docker image를 Artifact Registry에 저장하고, Argo CD가 deploy/ Helm Chart를 Kubernetes에 반영하는 방식으로 배포합니다. 저장소가 직접 정의하는 배포 자산은 cloudbuild.yaml, .github/workflows/onprem-cd.yml, deploy/ Helm Chart입니다. 두 delivery pipeline 모두 image와 GitOps desired state까지만 갱신하며 Kubernetes API를 직접 호출하지 않습니다.

이 문서는 배포 구조와 환경별 문서의 시작점입니다. 실제 명령과 설정은 GCP, On-premises, 배포 후 점검은 운영 및 검증에서 각각 관리합니다.

애플리케이션 저장소에서 kubectl apply나 helm upgrade를 직접 실행하지 않습니다.

1. 브랜치와 배포 환경¶

브랜치 용도는 2026-08-26 오너 결정으로 아래와 같이 정리되었습니다. main은 GCP production 배포 라인이며, 온프렘 배포 라인은 develop입니다.

브랜치	환경	Image build	배포 상태 갱신	클러스터 반영
`main`	GCP production	Cloud Build trigger `sohri-prd-graph-prd`	`deploy/values-prd.yaml`의 `image.tag` 자동 commit	Argo CD sync
`staging`	GCP development	Cloud Build trigger `sohri-dev-graph-dev`	`deploy/values-stg.yaml`의 `image.tag` 자동 commit	Argo CD auto sync
`develop`	On-premises	GitHub Actions `CD (on-prem)`	`mago-onprem-infra/main`의 중앙 `image.yaml` 직접 commit	관리자 Argo CD 수동 sync

main push는 이제 production 배포를 트리거합니다. 온프렘 배포는 main이 아니라 develop push에서만 시작합니다(.github/workflows/onprem-cd.yml의 push.branches: [develop]).

.github/workflows/cd.yml(CD (GKE fallback))은 workflow_dispatch 전용이며 자동 trigger가 없습니다. Cloud Build 경로가 막혔을 때만 수동으로 사용합니다.

Cloud Build trigger와 Argo CD Application은 이 저장소가 아니라 인프라 저장소 (sohri-gcp-infra)에서 정의하므로, 실제 활성 상태는 그쪽과 함께 확인합니다.

2. 전체 흐름¶

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"]

Chart 계약¶

values.yaml
├── values-stg.yaml       # GCP development (`staging` branch)
├── values-prd.yaml       # GCP production (`main` branch)
└── values-onprem.yaml    # On-premises runtime configuration

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을 렌더링합니다.

Maumon 장기 기억 설정¶

values.yaml의 maumon.enabled=true이면 base URL, 개별 HTTP timeout, 10000ms retrieval budget, query 수와 응답 크기 제한을 ConfigMap에 렌더링합니다. 인증 정보는 Chart가 생성하는 OpenAI ExternalSecret에 포함되지 않으므로 extraEnv와 별도 Kubernetes Secret으로 주입해야 합니다.

maumon:
  enabled: true
  baseUrl: "<maumon-base-url>"
  timeoutMs: 10000
  retrievalTimeoutMs: 10000
  maxEntityQueries: 3

extraEnv:
  - name: MAUMON_API_KEY
    valueFrom:
      secretKeyRef:
        name: sohri-maumon
        key: MAUMON_API_KEY

maumon.enabled는 ConfigMap 생성 switch일 뿐 실제 조회 여부를 결정하지 않습니다. Runtime은 Scenario의 metadata.memory_rag.enabled=true인 경우에만 조회합니다. 반대로 Scenario를 활성화해도 API key나 Session의 user.id가 없으면 조회를 건너뜁니다. 자세한 계약은 Maumon 장기 기억 조회를 참고합니다.

공통 endpoint는 deploy/values.yaml의 maumon.baseUrl에서 한 번만 선언합니다. 환경별 values 파일은 enabled와 Secret 식별자만 설정하고 endpoint를 상속합니다.

Session 저장소 모드¶

sessionStorage.mode는 memory 또는 redis입니다.

	`memory`	`redis`
저장 위치	process memory	공유 Redis
Pod 수	1로 고정(chart가 강제)	제한 없음
Pod 재시작	해당 Pod의 session 소실	유지
Redis 재시작	해당 없음	전 session 소실

redis 모드에서 sessionStorage.redis.deploy=true면 chart가 Redis Deployment와 Service(templates/redis.yaml)를 함께 만듭니다. 이 Redis는 replica 1 · 영속화 없음 · failover 없음입니다. 재시작하면 그 순간 살아있던 session이 전부 사라지고 모든 client가 "session not found"를 받습니다. 부하시험 중이라면 그것은 잠깐의 장애가 아니라 그날 밤 전체의 중단입니다. Memorystore 승격이 후속 작업이며, 그때는 deploy=false 로 두고 host 에 주소를 넣습니다.

연결 실패는 메모리로 조용히 폴백하지 않습니다. 폴백하면 Pod마다 다른 session을 보게 되고 증상은 "가끔 session을 못 찾는다"로만 나타나 원인 규명이 사실상 불가능해집니다. 그래서 redis 모드에서는 기동에 실패합니다.

강제되는 제한¶

sessionStorage.mode는 memory 또는 redis만 허용합니다.
memory 모드에서 replicaCount는 1보다 클 수 없습니다.
memory 모드에서 HPA를 켜더라도 maxReplicas는 1보다 클 수 없습니다.
redis 모드에서 deploy=false면 host가 필수입니다.
자체 호스팅 Redis는 requests == limits 여야 합니다. 어긋나면 GKE Autopilot이 admission에서 값을 고치고 Argo CD selfHeal이 되돌려 무한 재배포가 됩니다.
podAnnotations에 cluster-autoscaler.kubernetes.io/safe-to-evict를 넣을 수 없습니다. Autopilot이 "실행 시간 연장 Pod"로 승격해 같은 무한 재배포를 만듭니다.
GCP ExternalSecret은 External Secrets Operator와 GKE Workload Identity를 전제로 합니다.
On-prem은 기존 runtime Secret과 image pull Secret을 전제로 하며 ExternalSecret과 NEG를 끕니다.

문서¶

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