Operations

운영 작업은 render 확인, Argo CD 상태 확인, Kubernetes rollout 확인 순서로 진행합니다.

문제가 생겼을 때는 먼저 Git에 선언된 상태가 맞는지 확인하고, 그 다음 Argo CD가 그 상태를 sync했는지, 마지막으로 Kubernetes workload가 정상인지 확인합니다.

1. Render Checks

로컬에서 Kustomize output을 먼저 확인합니다.

kubectl kustomize clusters/dev/k3s/apps
kubectl kustomize clusters/dev/k3s/applications
kubectl kustomize clusters/stg/k3s/apps
kubectl kustomize clusters/stg/k3s/applications

Client-side dry-run으로 Kubernetes schema 수준의 오류를 더 확인할 수 있습니다.

kubectl kustomize clusters/dev/k3s/apps | kubectl apply --dry-run=client -f -

2. Argo CD Checks

Argo CD Application이 원하는 revision을 보고 있는지 확인합니다.

argocd app get tirosh-guide-dev --grpc-web
argocd app get tirosh-guide-stg --grpc-web

Dev는 automated sync를 사용합니다. Stg는 PR merge와 실제 배포 시점을 분리하기 위해 manual sync를 사용합니다.

Stg PR merge 후 OutOfSync이고 아직 배포 승인을 하지 않았다면 예상된 상태입니다. 승인 후에는 대상 Git revision, image tag와 digest, migration과 rollback 대상을 다시 확인하고 sync합니다.

argocd app sync tirosh-guide-stg --grpc-web

2-1. OutOfSync 판단

상황 다음 확인
Dev가 잠깐 OutOfSync 새 Git revision을 감지했는지와 operation 진행 상태
Dev가 계속 OutOfSync 최근 sync error, repository access, render diff
Stg merge 후 sync 전 OutOfSync 배포 승인과 검증 준비 여부
Stg sync 후 계속 OutOfSync Hook, immutable field, admission mutation, failed resource
Live patch 뒤 OutOfSync 변경을 Git에 반영할지, Git desired state로 복원할지

다음 항목을 함께 확인합니다.

argocd app diff tirosh-guide-stg --grpc-web
argocd app history tirosh-guide-stg --grpc-web

OutOfSync만 보고 반복해서 sync하지 않습니다. Desired state가 잘못됐으면 먼저 Git pull request로 고칩니다.

3. Registry와 image 확인

Stg promotion 전에는 exact tag와 top-level digest가 registry에 존재하고 OCI source revision이 release commit과 일치하는지 확인합니다.

docker buildx imagetools inspect \
  ghcr.io/tirosh-chain/guide/patient-risk-python-api:0.1.5

Rendered manifest에서도 승인한 tag와 digest를 확인합니다.

kubectl kustomize clusters/stg/k3s/apps | rg 'image:'

4. Kubernetes Checks

Workload 상태는 namespace 기준으로 확인합니다.

kubectl -n tirosh-guide-dev get deploy,pod,svc,ingress
kubectl -n tirosh-guide-stg get deploy,pod,svc,ingress

Image pull 실패는 describe pod 이벤트를 먼저 확인합니다.

kubectl -n tirosh-guide-stg describe pod <pod-name>

실제 Pod가 overlay와 같은 digest를 실행하는지도 확인합니다.

kubectl -n tirosh-guide-stg get pod \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .status.containerStatuses[*]}  {.name}: {.imageID}{"\n"}{end}{end}'

5. Stg component override

Component override는 Image Promotion의 조건과 기록 요건을 충족해야 합니다.

  1. 현재 complete release baseline의 tag와 digest를 기록합니다.
  2. Source change와 dependency를 기준으로 override set을 정합니다.
  3. sha-<git-sha> tag, digest, OCI source revision과 platform을 확인합니다.
  4. API, event, shared package와 schema compatibility를 검토합니다.
  5. Override set의 tag와 digest만 변경하는 pull request를 만듭니다.
  6. Render와 diff를 검토하고 merge한 뒤 stg를 manual sync합니다.
  7. 영향 workload, integration path와 업무 smoke를 확인합니다.
  8. 실패하면 baseline으로 rollback하고, 성공하면 다음 complete RC에 수렴시킵니다.

Override가 적용된 stg 상태를 complete product release로 해석하거나 prd 승격 근거로 사용하지 않습니다.

6. Rollback

Rollback은 이전에 승인한 tag와 digest로 Git desired state를 복원하는 pull request로 수행합니다.

  1. 이전 release 또는 override 전 baseline의 image 목록과 digest를 확인합니다.
  2. 현재 migration과 data가 이전 application version과 호환되는지 확인합니다.
  3. Overlay를 이전 release unit으로 되돌립니다.
  4. Kustomize render와 diff를 검토합니다.
  5. Merge 후 Argo CD를 sync하고 rollout과 업무 smoke를 다시 확인합니다.

Database schema가 이전 version과 호환되지 않으면 image만 되돌리지 않습니다. Migration 또는 data recovery 절차를 먼저 결정합니다.

Live resource만 kubectl set image나 kubectl patch로 되돌리지 않습니다. Incident 중 live patch가 불가피했다면 후속 pull request로 Git desired state와 반드시 일치시킵니다.

Argo CD의 이전 operation rollback 기능은 automated sync가 활성화된 Application에서 사용할 수 없습니다. Sync mode와 관계없이 재현 가능하고 지속되는 rollback 기준은 이전 digest를 복원하는 Git pull request입니다.

7. Docs Serving

이 CD repo는 docs image나 docs ingress를 배포하지 않습니다. 문서 사이트 서빙과 docs portal 운영은 별도 docs repository의 runbook을 따릅니다.