controller-runtime
Kubernetes 컨트롤러를 Go로 만들 때 쓰는 표준 라이브러리. ExternalSecret, ArgoCD, cert-manager 등 대부분의 K8s 오퍼레이터가 이 위에서 만들어진다.
컨트롤러의 핵심 루프(reconcile loop)를 추상화해서 제공한다. 개발자는 “이 리소스가 원하는 상태와 다를 때 뭘 할지”만 작성하면 된다. 나머지(watch, queue, retry)는 controller-runtime이 처리한다.
Reconcile Loop
컨트롤러의 기본 동작 방식이다.
리소스 변경 감지 → reconcile 함수 실행 → 성공/실패
reconcile 함수가 실패하면 controller-runtime이 자동으로 재시도를 스케줄링한다.
Backoff Requeue
에러가 발생했을 때 즉시 재시도하지 않는다. 지수 백오프(exponential backoff) 방식으로 대기 시간을 늘려가며 재시도한다.
1회 실패 → 약 1초 대기 → 재시도
2회 실패 → 약 2초 대기 → 재시도
3회 실패 → 약 4초 대기 → 재시도
...
이유는 단순하다. 실패의 원인이 일시적인 경우(네트워크 순단, 서버 부하 등)라면 잠깐 기다렸다가 재시도하면 해결된다. 즉시 재시도를 반복하면 오히려 시스템에 부하를 준다.
gRPC 연결 끊김과의 관계
ExternalSecret 컨트롤러가 gRPC 연결이 닫히는 순간에 TokenRequest API를 호출하면 에러가 발생한다. controller-runtime은 이 에러를 받아서 로깅하고(Reconciler error), backoff requeue를 수행한다. 약 5초 후 재시도할 때는 새 gRPC 연결이 수립되어 있어서 성공한다.