ArgoCD Sync Policy: Automated vs SelfHeal
정의 (Definition)
ArgoCD의 자동 동기화 정책에서 automated.enabled는 “Git의 변경이 발생했을 때” 클러스터에 반영하는 트리거이고, selfHeal은 “클러스터의 상태가 Git과 달라졌을 때(Drift)” Git 상태로 되돌리는 복구 메커니즘입니다. 두 옵션은 서로 배타적이지 않으며, GitOps의 완전성을 위해 상호 보완적으로 동작합니다.
문제가 되는 배경 (Problem Context)
“자동 동기화(automated: true)를 켰는데 왜 kubectl로 수정한 게 안 돌아오나요?” 또는 “HPA가 레플리카를 바꿨는데 selfHeal 때문에 자꾸 원복돼요”와 같은 혼란이 자주 발생합니다. 이는 두 옵션의 **트리거 조건(Trigger Condition)**과 방향성을 혼동하기 때문입니다.
핵심 메커니즘 (How it Works)
| 기능 | 트리거 조건 | 방향성 | 역할 |
|---|---|---|---|
automated.enabled | Git Commit 발생 (Desired State 변경) | Git → Cluster | 새로운 배포 자동화 |
selfHeal | Live State 변경 (Cluster Drift 감지) | Cluster → Git | 수동 변경 방지 및 상태 유지 |
ArgoCD의 Reconciliation 루프는 다음과 같이 동작합니다.
- Git 저장소 폴링 → 변경 감지 →
automated가 켜져 있으면 Sync 실행. - Kubernetes Watch 이벤트 → 리소스 변경 감지 → Git과 비교 → 차이(Drift) 발생 시
selfHeal이 켜져 있으면 Sync 실행.
불변 조건과 보장 범위 (Invariants & Guarantees)
- 독립적 동작:
automated만 켜져 있으면, 클러스터에서kubectl edit으로 리소스를 망가뜨려도 ArgoCD는 OutOfSync 상태만 표시할 뿐, 다음 Git 커밋이 있을 때까지 복구하지 않습니다. - Drift 복구:
selfHeal이 켜져 있으면, 클러스터의 변경 사항은 즉시(또는 짧은 지연 후) Git에 정의된 상태로 강제 덮어쓰기(Revert) 됩니다.
비유 (Analogy)
automated.enabled: “악보가 바뀌면 연주를 바꾼다.” (작곡가의 의도 반영)selfHeal: “연주자가 실수로 딴 음을 내면 즉시 지적하고 교정한다.” (연주의 정확성 유지)
실무적 함의 (Operational Implications)
- 완전한 GitOps: Git을 유일한 진실 공급원(Single Source of Truth)으로 유지하려면 두 옵션을 모두 활성화해야 합니다.
- HPA와의 충돌: HPA, KEDA 등 외부 컨트롤러가 리소스(예:
replicas)를 동적으로 변경하는 경우,selfHeal이 이를 Drift로 인식하여 싸울 수 있습니다. 이때는selfHeal을 끄는 것이 아니라,ignoreDifferences설정으로 해당 필드만 무시하는 것이 올바른 해법입니다.
주의사항 / 오해 (Pitfalls & Misconceptions)
- “자동 동기화를 켜면 복구도 된다?”: 아닙니다.
automated는 Git 변경에만 반응합니다. - “HPA 쓰면 selfHeal 꺼야 한다?”: 잘못된 접근입니다.
replicas필드만 예외 처리하고selfHeal은 켜두어야 보안 설정 변경 등 다른 Drift를 막을 수 있습니다.
References
- Argo CD Docs: Automated Sync Policy
- Related Note: ArgoCD_IgnoreDifferences_Pattern