ArgoCD의 timeout.hard.reconciliation 이란?

 

이벤트를 놓쳐도 결국 상태를 맞추는 마지막 안전장치

Argo CD 를 운영하다 보면 가끔 이런 상황이 발생한다.

• Git은 정상인데 ArgoCD가 변경을 감지하지 못함
• 실제 리소스가 바뀌었는데 Sync 상태가 그대로임
• kubectl edit 로 변경했는데 바로 drift 로 안 잡힘
• selfHeal 이 켜져 있는데도 복구가 늦음

이런 현상의 핵심에는
ArgoCD의 reconciliation 구조와 cache/informer 기반 동작 방식이 있다.

그리고 이를 보완하는 중요한 설정 중 하나가 바로:

 

timeout.hard.reconciliation

 

이다.

---

reconciliation 이란?

ArgoCD에서 reconciliation 은:

Git의 desired state 와
실제 Kubernetes live state 를 비교하는 과정

이다.

즉:

Git 상태 == 현재 클러스터 상태 ?

 

를 지속적으로 확인한다.

ArgoCD의 핵심 자체가 결국 이 reconciliation loop 에 기반한다.

---

ArgoCD는 어떻게 상태를 감지할까?

ArgoCD는 단순 polling 만 하는 시스템이 아니다.

주로 다음 기반으로 동작한다.

• Kubernetes Informer Event
• Git Polling
• Webhook
• Cache
• Resource Watch

즉:

"변경 이벤트가 발생하면 다시 비교"

 

구조다.

그래서 일반적인 경우에는 매우 빠르게 drift 를 감지한다.

---

그런데 왜 문제가 발생할까?

현실 운영에서는 다음 상황이 발생할 수 있다.

• informer event 유실
• controller restart
• cache stale
• network issue
• webhook 실패
• API Server 일시 문제
• 대규모 cluster 에서 watch 누락
• 외부 수동 변경 (kubectl edit)

즉:

"변경은 있었는데 ArgoCD가 이벤트를 못 봄"

 

상황이 생길 수 있다.

---

여기서 등장하는 timeout.hard.reconciliation

이 설정은:

이벤트 여부와 관계없이
일정 시간이 지나면 전체 상태를 강제로 다시 비교

하도록 만든다.

즉:

"혹시 놓친 거 없나? 다시 전체 검사해"

 

개념이다.

---

일반 reconciliation 과 차이

timeout.reconciliation

 

timeout.reconciliation: 120s

 

이건 일반 Git polling 주기다.

즉:

• Git repo refresh
• 변경 여부 확인

에 가깝다.

---

timeout.hard.reconciliation

 

timeout.hard.reconciliation: 10m

 

이건 더 강한 개념이다.

단순 polling 이 아니라:

• cluster refresh
• cache bypass
• full comparison
• live state 재조회

에 가까운 강제 reconciliation 이 수행된다.

즉:

"캐시 믿지 말고 다시 제대로 비교"

 

하는 동작이다.

---

설정 위치

보통 argocd-cm ConfigMap 에 설정한다.

 

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
data:
  timeout.reconciliation: 120s
  timeout.hard.reconciliation: 10m

 

---

0s 의 의미

 

timeout.hard.reconciliation: 0s

 

이면:

hard reconciliation 비활성화

의미다.

즉:

• 이벤트 기반 동작만 사용
• 일반 reconciliation 만 수행

한다.

---

운영에서 왜 중요할까?

실제 운영에서는:

"이벤트 기반 시스템은 절대 100% 신뢰할 수 없다"

 

는 점이 매우 중요하다.

특히 Kubernetes ecosystem 은:

• informer
• cache
• watch stream

기반 시스템이 많다.

이 구조는 성능은 좋지만:

이벤트 miss 가능성은 완전히 0 이 아니다.

그래서 hard reconciliation 이:

최종 consistency 보장 장치

역할을 한다.

---

selfHeal 과의 관계

많이 오해하는 부분이다.

 

syncPolicy:
  automated:
    selfHeal: true

 

를 켜도:

• 이벤트를 못 봤다면
• drift 자체를 감지 못했다면

자동 복구가 바로 안 될 수 있다.

이때 hard reconciliation 이 주기적으로 전체 상태를 재검사하면서:

"아 drift 있었네?"

 

를 발견하고 복구한다.

---

너무 짧게 잡으면?

예:

 

timeout.hard.reconciliation: 1m

 

이면:

• API Server 부하 증가
• repo-server 부하 증가
• 비교 연산 증가
• controller CPU 증가

문제가 발생할 수 있다.

특히:

• App 수백 개 이상
• Large Cluster
• Multi Cluster

환경에서는 영향이 커질 수 있다.

---

너무 길게 잡으면?

예:

 

24h

 

처럼 길면:

• drift 발견 지연
• selfHeal 지연
• 이벤트 miss 복구 늦음

문제가 생긴다.

---

실무에서 자주 사용하는 값

보통 많이 사용하는 범위는:

10m
30m
1h

 

정도다.

환경 규모에 따라 다르다.

환경추천 경향

소규모	10m
일반 운영	30m
대규모 Cluster	1h

---

핵심 정리

timeout.hard.reconciliation 은:

이벤트 기반 감지 실패 가능성을 보완하기 위한
ArgoCD의 강제 전체 상태 재검사 주기

이다.

즉:

• drift 복구 안정성 확보
• cache stale 대응
• informer miss 대응
• eventual consistency 보장

을 위한 매우 중요한 운영 옵션이다.

특히:

“왜 selfHeal 인데 복구가 늦지?”

같은 현상을 이해할 때 반드시 알아야 하는 설정이다.