본문으로 건너뛰기
· infra · 2분 읽기

Argo CD PreSync로 DB 마이그레이션 실행 순서 관리하기

애플리케이션이 새 컬럼을 사용하는데 DB 변경이 끝나지 않았다면 배포 직후 요청이 실패할 수 있다. 반대로 DB에서 기존 컬럼부터 제거하면 아직 실행 중인 이전 버전이 실패한다. 실행 순서와 스키마 호환성을 함께 다뤄야 한다.

구현한 범위

PostgreSQL 운영 연결 설정을 전환하고 개발·운영 환경에 Argo CD PreSync 마이그레이션 Job을 추가했다. PHP 마이그레이션 도구를 애플리케이션 동기화 전에 실행하도록 배치하고 실행 제한 시간과 재시도 정책을 명시했다. 아래는 가상 서비스로 재구성한 구성이다.

마이그레이션을 별도 Job으로 실행한다

yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: sample-api-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation,HookSucceeded
spec:
  backoffLimit: 1
  activeDeadlineSeconds: 300
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: registry.example.com/sample-api:release-001
          command: ["php", "/app/bin/migrate.php"]
          envFrom:
            - secretRef:
                name: sample-api-database

이미지, 명령, Secret 이름과 제한 값은 설명용이다. 실행 가능한 이미지는 제공하지 않는다. 애플리케이션과 Job이 같은 릴리스의 코드를 사용하도록 관리하고, 실제 배포에서는 변경되지 않는 이미지 식별자를 사용한다.

PreSync가 성공해야 Sync 단계로 진행한다. 고정 이름의 Job은 BeforeHookCreation으로 이전 리소스를 정리한 뒤 다시 생성하고, 성공한 Job은 HookSucceeded로 정리한다. 선택적 동기화에서는 hook이 실행되지 않으므로 Deployment만 동기화하는 경로를 별도로 점검해야 한다. 동작 기준은 Argo CD의 sync 단계와 hook 정책이다.

Job이 참조하는 Secret은 실행 전에 존재해야 한다. 같은 Application의 일반 Sync 리소스로 Secret을 처음 만들면 PreSync에서 사용할 수 없다. 이 예제는 필요한 Secret과 DB 접속 경로가 사전에 준비된 상태를 전제로 한다.

실행 순서가 해결하지 못하는 부분

마이그레이션 중에는 이전 애플리케이션이 계속 실행될 수 있다. 새 컬럼을 추가하고 데이터를 보정한 뒤 애플리케이션을 전환하고, 이전 버전 사용이 끝난 후 기존 컬럼을 제거하는 식으로 변경을 나눈다. PreSync 성공은 무중단 전환의 증거가 아니다.

Job 재시도나 다음 동기화에서 명령이 다시 실행될 수 있다. 마이그레이션 도구의 적용 이력과 동시 실행 제어가 필요하다. 여러 Application이 같은 DB를 변경한다면 한 Application 안의 실행 순서만으로는 부족하다.

실패했다고 이미 적용한 변경이 자동으로 취소되지는 않는다. 일부 단계가 반영된 상태에서 재실행할 수 있는지, 이전 애플리케이션으로 복귀할 수 있는지를 별도로 설계한다. 성공 Job을 삭제하면 사후 분석에 쓸 Pod 로그도 사라질 수 있으므로 로그 보존 경로도 필요하다.

재현할 조건과 확인 범위

작성한 경험의 근거는 코드·매니페스트 기여다. 이 공개 예제를 클러스터에서 실행한 결과나 운영 전환 지표는 없다.

재현 조건확인할 결과
마이그레이션 명령 실패새 애플리케이션의 Sync 진행 여부와 기존 버전 상태
실행 제한 시간 초과Job 실패 상태와 DB에 남은 변경
같은 릴리스 재동기화이미 적용한 변경의 중복 실행 방지
Secret이 없는 첫 배포Job 시작 실패 원인과 선행 리소스 준비 순서
이전 버전과 새 스키마 조합기존 읽기·쓰기 계약 유지 여부
Deployment만 선택적 동기화마이그레이션을 우회하는 배포 경로 탐지
공유하기 X LinkedIn

관련 글