Automated Sync Policy — Git과 클러스터 차이를 자동으로 맞추기

수동으로 'Sync' 버튼을 누르는 대신, Git의 원하는 상태와 클러스터의 라이브 상태가 달라지면 Argo CD가 스스로 동기화하게 만들 수 있어요. 이렇게 하면 CI/CD 파이프라인이 Argo CD API 서버에 직접 붙을 필요 없이, 그냥 Git에 커밋·푸시만 해도 배포가 이뤄집니다.

출처: Argo CD 공식 문서 — Automated Sync Policy

본문

자동 싱크를 켜는 가장 간단한 방법은 CLI로 동기화 정책을 automated로 바꾸는 거예요.

argocd app set <APPNAME> --sync-policy automated

매니페스트로 만든다면 syncPolicy에 automated를 넣어요.

spec:
  syncPolicy:
    automated: {}

Application CRD에서 spec.syncPolicy.automated.enabled 플래그로 켜고 끌 수도 있어요. false로 두면 prune·selfHeal·allowEmpty가 설정돼 있어도 컨트롤러가 자동 싱크를 건너뜁니다. 참고로 enabled를 null로 두는 것은 켠 것과 같은 의미예요.

자동 프루닝

기본적으로(안전 장치로) 자동 싱크는 Git에 더 이상 없는 리소스를 삭제하지 않아요. 프루닝은 언제든 수동 싱크로 할 수 있고, 자동 싱크에서도 되게 하려면:

argocd app set <APPNAME> --auto-prune

정책으로는 prune: true를 줍니다.

spec:
  syncPolicy:
    automated:
      prune: true

비어 있는 리소스 허용 — Allow-Empty

프루닝을 켠 자동 싱크는 기본적으로 "대상 리소스가 아예 없다"는 실수(자동화·사람 오류)를 보호해요. 빈 리소스를 허용하려면:

argocd app set <APPNAME> --allow-empty

spec:
  syncPolicy:
    automated:
      prune: true
      allowEmpty: true

자동 자기 치유 — Self-Healing

기본적으로 라이브 클러스터에 직접 낸 변경은 자동 싱크를 트리거하지 않아요. Git에 정의된 상태에서 벗어났을 때도 자동으로 되돌리려면 셀프힐을 켜요.

argocd app set <APPNAME> --self-heal

spec:
  syncPolicy:
    automated:
      selfHeal: true

셀프힐을 껐다고 해서 멀티 소스 애플리케이션의 라이브 변경이 반드시 보존되진 않는다는 점은 알아두세요. 한 소스는 그대로여도 다른 소스의 변경이 autosync를 유발할 수 있으니, 그런 경우엔 autosync 자체를 끄는 걸 고려해요.

자동 재시도 — 지수 백오프

실패한 싱크를 지수 백오프로 자동 재시도하게 할 수 있어요.

spec:
  syncPolicy:
    retry:
      limit: 5  # 재시도 횟수 (-1이면 무제한)
      backoff:
        duration: 5s  # 첫 재시도 전 기본 대기
        factor: 2     # 실패할 때마다 곱해지는 배수
        maxDuration: 3m  # 재시도 간 최대 대기

limit: 재시도 횟수. -1이면 무제한.
backoff.duration: 첫 재시도 전 기본 대기 시간.
backoff.factor: 실패할 때마다 기본 대기에 곱해지는 배수.
backoff.maxDuration: 시도 횟수와 무관한 최대 대기 시간.

새 리비전이 생기면 재시도 중에도 리프레시를 하게 하려면 --sync-retry-refresh 플래그나 retry.refresh: true를 쓰면 돼요.

자동 싱크의 동작 규칙 (시맨틱스)

자동 싱크가 어떤 상황에서 돌고 멈추는지 정확히 알면 운영이 편해져요.

자동 싱크는 애플리케이션이 OutOfSync 상태일 때만 수행돼요. Synced나 오류 상태에서는 시도하지 않습니다.
커밋 SHA1과 애플리케이션 파라미터 조합당 한 번만 시도해요. 히스토리의 가장 최근 성공 싱크가 이미 같은 커밋·파라미터로 수행된 것이라면, selfHeal이 켜져 있지 않는 한 다시 싱크하지 않아요.
selfHeal이 켜져 있으면 셀프힐 타임아웃(기본 5초, argocd-application-controller의 --self-heal-timeout-seconds로 제어) 후 다시 시도해요.
같은 커밋·파라미터로 앞선 싱크가 실패했었다면 자동 싱크는 재시도하지 않아요.
자동 싱크가 켜진 애플리케이션은 롤백을 수행할 수 없어요. 롤백을 쓰려면 자동 싱크를 먼저 꺼야 한다는 점, 꼭 기억하세요.
자동 싱크 간격은 argocd-cm ConfigMap의 timeout.reconciliation 값으로 정해지며, 기본 120초에 60초의 지터(jitter)를 더해 최대 3분입니다.

Automated Sync Policy — Git과 클러스터 차이를 자동으로 맞추기