복세편살 개발라이프
프로그래밍 & IT › Infra

Argo CD 동기화 성공인데 마이그레이션 누락: sync window와 self-heal 경쟁 조건

· 읽는 시간 5분

목차
  1. 3줄 요약
  2. 무엇이 바뀌었나
  3. 운영 관점에서 볼 점
  4. 적용해 보려면
  5. 정리
  6. 참고 자료

3줄 요약

  • deny sync window(특정 시간대에 동기화를 막는 설정)가 닫히는 순간, Argo CD가 정식 배포 대신 self-heal(드리프트 복구)을 먼저 실행하면 hook으로 걸어 둔 DB 마이그레이션이 실행되지 않을 수 있습니다 [1].
  • 이때 UI에는 Synced·Healthy로 표시되고 작업 결과도 정상으로 남기 때문에 화면만으로는 문제를 알아채기 어렵습니다 [1].
  • CNCF 글은 PreSync 전환이나 RunHooksOnPartialSync 옵션으로는 해결되지 않는다고 보고, 마이그레이션 Job을 hook이 아닌 일반 관리 리소스로 바꾸라고 권합니다 [1].

무엇이 바뀌었나

새 기능이 생긴 것은 아니고, 기존 동작에 숨어 있던 경쟁 조건(race condition, 먼저 도착한 이벤트에 따라 결과가 달라지는 문제)이 구체적으로 밝혀졌습니다 [1].

사례는 이렇습니다. 한 서비스를 리전별 Application 5개로 운영하고, 자동 동기화에 prune과 self-heal을 켠 상태였습니다. 운영 환경은 업무 외 시간에 deny window로 막혀 있었고, 마이그레이션은 Sync hook Job으로 실행됐습니다 [1]. window가 활성화된 동안 릴리스를 올렸고, window가 열리자 5개 중 3개만 마이그레이션을 돌렸습니다. 나머지 2개는 36~44분 동안 새 코드가 옛 스키마를 상대했다고 합니다 [1].

원인은 refresh 종류에 있습니다. 글에 따르면 Argo CD의 refresh는 두 가지입니다 [1].

  • level-2 refresh: 대략 2~3분 주기의 타이머로 발생하며 Git과 비교합니다 [1].
  • level-1 refresh: 관리 대상 오브젝트가 바뀔 때 발생하며 컨트롤러가 이미 가진 정보를 재사용합니다 [1].

window가 닫혀도 별도 신호는 없고, 그다음 도착하는 refresh가 이후 동작을 결정합니다 [1]. window 기간 중 타이머 refresh는 새 커밋을 status.sync.revision에 기록하지만 실제 마지막 동기화는 옛 커밋에 머뭅니다 [1]. 이후 level-1 refresh가 먼저 오면 기록된 리비전을 자기 자신과 비교해 변경 없음으로 판단하고(evaluateRevisionChanges), alreadyAttemptedSync도 소스가 그대로라 이미 동기화했다고 결론 냅니다 [1]. 결국 self-heal이 어긋난 리소스만 맞추는 부분 동기화를 실행하는데, 부분 동기화는 hook을 실행하지 않고 히스토리도 남기지 않습니다 [1]. 필자는 이를 마지막으로 비교한 리비전을 마지막으로 동기화한 리비전으로 착각하는 버그라고 요약합니다 [1].

운영 관점에서 볼 점

  • 탐지 난이도: 문제 Application도 새 커밋 기준 Synced·Healthy였고 마지막 작업 메시지는 "successfully synced (all tasks run)"였습니다 [1]. 단서는 컨트롤러 로그뿐이었는데, 문제 작업에는 특정 리소스 13개가 나열되고 self-heal 시도 횟수가 1로 찍혀 있었습니다 [1].
  • 재현성: 필자의 실험 환경에서는 6번 중 5번 재현됐습니다 [1]. 드문 사고가 아니라 이벤트 순서만 맞으면 누구나 겪을 수 있다는 뜻입니다.
  • 흔한 우회책의 한계: 코드 분석상 부분 동기화는 모든 hook 유형을 건너뛰므로 PreSync로 바꿔도 같고, RunHooksOnPartialSync는 자동 동기화에서 무시되며 self-heal은 본질적으로 자동 동기화입니다 [1]. window 길이와 무관하게 닫힐 때마다 경쟁이 생기므로 window를 줄여도 소용없다고 합니다 [1]. 다만 필자는 이 세 가지를 직접 시험하지는 않았다고 밝혔습니다 [1].
  • 설계 교훈: hook은 특정 종류의 작업이 돌 때만 실행되므로, 다른 경로로 릴리스가 반영될 수 있다면 보장이 아니라 기대에 가깝다는 지적입니다 [1].

적용해 보려면

  1. 현황 점검: 자동 동기화·self-heal·deny window를 함께 쓰면서 마이그레이션을 hook으로 돌리는 Application을 찾습니다. 이 조합이 글의 사례와 같습니다 [1].
  2. 실행 여부 확인 수단 마련: 필자는 Job에 릴리스 라벨을 붙여 어느 버전 마이그레이션이 마지막으로 돌았는지 바로 보이게 했습니다 [1]. UI 상태 대신 이런 근거로 검증하는 편이 안전합니다.
  3. hook 제거, desired state로 편입: hook 어노테이션을 지우고, 앱보다 먼저 실행되도록 sync wave를 주며, 릴리스마다 이름이 바뀌게 합니다 [1].
yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration-v11
  annotations:
    argocd.argoproj.io/sync-wave: "-1"

이렇게 하면 새 릴리스마다 아직 없는 Job이 생기므로 마이그레이션이 일반 관리 리소스로 다뤄집니다 [1]. 부분 동기화에서도 이 Job이 어긋난 리소스로 잡힌다는 취지로 보이지만, 자료의 해당 부분이 잘려 있어 세부 설명은 확인되지 않았습니다. 이전 릴리스 Job 정리 방식도 자료에 없으므로 별도로 검토해야 합니다.

정리

'동기화 성공'은 hook이 실행됐다는 뜻이 아닐 수 있습니다. sync window가 닫히는 시점에 level-1 refresh가 먼저 오면 self-heal의 부분 동기화가 hook을 건너뜁니다 [1]. 마이그레이션처럼 반드시 실행돼야 하는 작업은 동기화의 부수 효과로 두지 말고, 릴리스마다 이름이 바뀌는 Job으로 desired state에 포함하는 방향을 검토할 만합니다 [1].

참고 자료

  1. When a sync window closes: How Argo CD self-heal skipped the migration hook · CNCF, 2026-11-20

#Argo CD#Kubernetes#GitOps#sync window#self-heal#DB 마이그레이션