Alembic · ArgoCD · Pre-Deployment Hook 통합

Zero-Downtime DB 마이그레이션을 위한 GitOps 기반 자동화 전략:

⸻

1. 배경: 데이터베이스 마이그레이션이 무서운 이유

서비스에서 가장 보수적으로 다뤄야 하는 컴포넌트는 데이터베이스입니다. 특히 스키마 변경이나 DDL/DML 반영은 다음과 같은 위험을 동반합니다.
• 다운타임 유발 (Lock, Block, Long Transaction 등)
• 롤백 불가능한 변경 (Drop, Alter without backup)
• 스테이징/운영 환경 스키마 불일치

이를 해결하기 위한 접근법이 바로 Zero-Downtime Migration, 그리고 GitOps 기반 자동화 배포입니다.

⸻

2. 기술 스택 및 구성 요소

구성 요소 설명
Alembic SQLAlchemy 기반 Python DB 마이그레이션 도구
ArgoCD GitOps 방식의 쿠버네티스 애플리케이션 배포
Pre-deploy Hook 마이그레이션 수행 후 애플리케이션 배포 트리거
Post-deploy Hook 배포 후 검증 쿼리 또는 알림 자동화
K8s Job Alembic 마이그레이션을 위한 단발성 컨테이너 실행


⸻

3. 마이그레이션 자동화 Git 구조

infra/
├── argocd-apps/
│   ├── myapp.yaml
│   └── hooks/
│       ├── pre-deploy-migration.yaml  ← Alembic 실행 Job
│       └── post-deploy-verify.yaml    ← 결과 검증용 Job
├── manifests/
│   ├── myapp/
│   │   └── deployment.yaml
├── db/
│   └── versions/
│       ├── 20230501_add_column.py
│       └── 20230615_drop_table.py


⸻

4. ArgoCD Hook 활용 예시

pre-deploy-migration.yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: alembic-migration
  annotations:
    "argocd.argoproj.io/hook": PreSync
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: myregistry/alembic-runner:latest
        command: ["alembic", "upgrade", "head"]
        envFrom:
          - configMapRef:
              name: db-config
      restartPolicy: Never


⸻

post-deploy-verify.yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: schema-verify
  annotations:
    "argocd.argoproj.io/hook": PostSync
spec:
  template:
    spec:
      containers:
      - name: check
        image: myregistry/alembic-runner:latest
        command: ["alembic", "current"]
        envFrom:
          - configMapRef:
              name: db-config
      restartPolicy: Never


⸻

5. Alembic 관리 전략
• 마이그레이션 스크립트는 모두 Git 관리
• 각 마이그레이션 파일은 명시적 버전(날짜 기반)
• 테스트 환경에서 반드시 alembic upgrade --sql 로 dry-run
• 운영 반영 전 alembic history로 변경 이력 리뷰 필수

alembic revision -m "add user table"
alembic upgrade head
alembic downgrade -1


⸻

6. 추가 고급 전략

전략 설명
Shadow Write 신규 컬럼에 동시에 기록, 구 데이터 유지
Dual Read (Read Switch Gradually) 신규 컬럼 값 우선 조회, 예외 발생 시 구값 fallback
Blue-Green DB Replica Aurora Read Replica로 마이그레이션 선행 적용
Trunk-Based Migration 마이그레이션도 CI/CD에 통합하여 trunk 단일 truth 유지


⸻

7. 결론

Zero-Downtime DB 마이그레이션은 단순히 Alembic을 쓰는 수준을 넘어
GitOps 배포에 통합된 자동 실행 체계로 관리되어야 합니다.

CI/CD, Git, Kubernetes, 그리고 데이터 마이그레이션을
하나의 파이프라인 안에 재현 가능하고 리버서블하게 구성할 때,
실제 운영에서 예측 가능하고 안전한 배포가 가능해집니다.