배포 운영¶

배포 전 검증¶

helm lint deploy -f deploy/values-dev.yaml
helm lint deploy -f deploy/values-prd.yaml
helm lint deploy -f deploy/values-onprem.yaml

helm template sohri-graph deploy \
  --namespace sohri \
  -f deploy/values-dev.yaml

python -m pytest -q dm/tests/test_deploy_docs.py

On-prem의 실제 최종 manifest를 검증하려면 외부 GitOps 저장소의 현재 image.yaml과 Application이 적용하는 override를 추가해 render해야 합니다. test_deploy_contract.py 전체는 현재 on-prem workflow 기대값이 실제 workflow와 불일치하므로, 그 실패를 배포 계약 위반으로 단정하기 전에 알려진 불일치를 확인합니다.

flowchart LR
    VALUES["Chart + environment values"] --> RENDER["helm lint/template"]
    RENDER --> DIFF["Argo CD diff"]
    DIFF --> SYNC["환경 정책에 따른 sync"]
    SYNC --> ROLLOUT["Rollout"]
    ROLLOUT --> SMOKE["API smoke test"]

확인할 값:

정확한 image repository와 immutable tag
release/namespace와 Service port 59212
runtime Secret 이름과 OPENAI_API_KEY
replica 1, HPA 비활성
GCP의 Project/GSA/NEG/ESO 좌표
On-prem의 외부 image overlay와 Skill Runtime endpoint

Rollout 확인¶

kubectl -n <namespace> get deployment,replicaset,pod,service
kubectl -n <namespace> rollout status deployment/<name>
kubectl -n <namespace> describe pod <pod-name>
kubectl -n <namespace> logs deployment/<name>

Startup probe는 현재 설정상 initial delay 10초 후 10초 간격으로 최대 30회 실패를 허용합니다. Readiness 통과, Service endpoint 등록, Secret resolution과 반복적인 liveness 실패가 없는지 확인합니다. GCP에서는 NEG backend health도 별도로 봅니다.

변경 반영¶

변경	manifest 동작
`image.tag`	Deployment rolling update
ConfigMap 값	`checksum/config` 변경으로 rolling update
Kubernetes Secret	Reloader가 설치·활성화된 경우 Pod restart
Probe/resource/security 값	Deployment rolling update
Service/NEG	Service 갱신

ESO의 기본 refresh interval은 1시간입니다. Environment variable은 실행 중인 process에서 자동 갱신되지 않으므로 Secret 변경을 반영하려면 Reloader 또는 수동 rollout이 필요합니다.

Session 제한¶

SessionManager와 session별 runtime이 process memory에 있으므로 Pod가 재시작되면 session이 소실되고 다른 Pod는 session을 복원할 수 없습니다. Chart validation은 sessionStorage.mode=memory, replicaCount<=1, HPA maxReplicas<=1을 강제합니다. 현재 values는 replica 1과 HPA 비활성입니다.

Rollback¶

GCP: 해당 환경 values의 image.tag를 이전 immutable SHA로 commit하고 외부 Argo CD 정책에 따라 반영합니다.
On-prem: 외부 gitops/apps/values/sohri-graph-builder-onprem/image.yaml을 이전 12자 SHA로 commit하고 관리자가 Argo CD diff 후 sync합니다.

latest를 rollback 기준으로 사용하지 않습니다.

장애 점검¶

증상	우선 확인
`ImagePullBackOff`	repository/tag, image pull Secret, registry 권한
Pod Ready 실패	`/` probe, port `59212`, resource, application log
OpenAI 인증 실패	runtime Secret, ESO/GSA 또는 on-prem Secret, rollout 여부
Skill 호출 실패	`sohri-skill-runtime:59213`, EndpointSlice, Runtime log
GCP traffic 실패	NEG 이름, endpoint health, load balancer backend
On-prem tag 갱신 실패	GitHub App 설치/secrets, 외부 main ruleset, rebase log

최종적으로 /, /v1과 실제 session/message 흐름을 smoke test하고 이전 정상 image tag를 기록합니다.