Kubernetes Operator의 RequeueAfter 개념

Kubernetes Operator를 만들 때 Reconcile 루프를 일정 시간 후 다시 실행하도록 예약하는 메커니즘입니다.
Kubernetes의 controller-runtime 라이브러리에서 주로 사용되고, 특히 외부 상태 동기화, 실패 재시도, 일정 주기 polling이 필요할 때 유용해요.

 

기본 개념: RequeueAfter

return ctrl.Result{RequeueAfter: 30 * time.Second}, nil

 

이 코드는 다음과 같은 의미예요:

"현재 리소스에 대해 30초 후에 다시 Reconcile을 호출해줘."

즉, Reconcile을 강제로 예약해서 재호출하도록 만드는 기능입니다.

 

왜 필요할까?

Reconcile() 함수는 일반적으로 리소스에 이벤트가 발생했을 때만 호출됩니다.
하지만 다음과 같은 경우에도 Reconcile을 반복 호출하고 싶을 때가 있어요:

 

상황예시

외부 시스템 상태와 정기적으로 동기화	외부 API의 응답값을 .status에 반영해야 할 때
특정 작업의 진행 상태를 주기적으로 확인	Job 상태 확인, 백업 완료 여부 확인 등
실패한 작업 재시도	외부 API 실패 후 몇 초 뒤 다시 시도
타임아웃 또는 상태 만료 감지	5분 이상 Running 상태면 실패로 간주 등

이럴 때 RequeueAfter를 사용하면 이벤트 없이도 주기적으로 루프를 재진입시킬 수 있어요.

 

사용 예시

 

func (r *MyResourceReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 리소스 가져오기
    var myRes v1alpha1.MyResource
    if err := r.Get(ctx, req.NamespacedName, &myRes); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 외부 상태 확인
    status, err := r.ExternalAPI.GetStatus(myRes.Spec.ID)
    if err != nil {
        log.Error(err, "외부 상태 확인 실패")
        // 10초 뒤 다시 시도
        return ctrl.Result{RequeueAfter: 10 * time.Second}, nil
    }

    // 상태가 아직 완료되지 않았으면 재시도
    if status != "COMPLETED" {
        return ctrl.Result{RequeueAfter: 1 * time.Minute}, nil
    }

    // 상태 완료 → 정상 처리
    myRes.Status.Phase = "Done"
    _ = r.Status().Update(ctx, &myRes)

    return ctrl.Result{}, nil
}

 

주의할 점

주의사항설명

너무 짧은 주기 사용 금지	API 서버나 외부 API에 부하 발생 가능
필요할 때만 사용	상태 변화가 없는데도 계속 호출되면 anti-pattern
비동기 작업 추적에 적합	외부 Job 처리, 장시간 작업 추적 등에 유용

 

Requeue vs RequeueAfter 차이

항목설명

Requeue: true	즉시 Reconcile을 다시 호출 (즉시 재시도)
RequeueAfter: x	x 시간 후에 Reconcile 재호출 (지연된 재시도)

 

요약

• RequeueAfter는 일정 시간 후 Reconcile을 예약하는 기능
• 이벤트가 없더라도 주기적인 재확인이 필요한 상황에 유용
• Kubernetes는 기본적으로 이벤트 기반이지만, RequeueAfter를 통해 Polling-like behavior도 가능
• 잘못 사용하면 과도한 루프 발생 → 신중하게 조건부로 사용