controller-runtime 캐시가 실제로 동작하는 방식, 그리고 왜 당신 컨트롤러가 API 서버를 죽이지 않는가

kubebuilder로 컨트롤러 한번 만들어본 사람이라면 다들 겪는 순간이 있다. r.Get()으로 방금 r.Update() 친 오브젝트를 다시 읽었는데 옛날 값이 나온다. "어? 방금 바꿨는데?" 하고 로그 찍어보고, 재현 안 되고, 그러다 넘어간다. 근데 이게 부하 올라가면 실서비스에서 터진다.

이 글은 그 "왜 옛날 값이 나오지?"의 근본 원인인 controller-runtime 캐시를 뜯어본다. 원문은 Kubernetes 공식 블로그의 How the controller-runtime Cache Actually Works(Andrei Kvapil, Timofei Larkin)를 기반으로 하고, 실무에서 실제로 밟는 지뢰 위주로 재구성했다.

1. 왜 지금 이걸 알아야 하는가

요즘 사내 플랫폼팀에서 CRD + 컨트롤러 조합으로 자동화 짜는 게 거의 표준이 됐다. kubebuilder 스캐폴딩 돌리면 몇 시간 만에 동작하는 컨트롤러가 나온다. 문제는 그다음이다. 트래픽 없을 땐 잘 돌던 게, 오브젝트 수만 개 규모에서 갑자기 이상하게 군다.

대부분의 사람이 갖고 있는 잘못된 멘탈 모델은 이렇다:

• r.Get()은 kube-apiserver를 직접 조회한다
• r.List()는 실시간 상태를 돌려준다
• r.Update() 직후 다시 읽으면 새 값이 바로 보인다

셋 다 틀렸다. 실제로는 정반대다. controller-runtime은 list + watch로 채워둔 로컬 인메모리 복사본을 상대로 읽는다. 그래서 reconcile 안에서 초당 수백 번 읽어도 컨트롤 플레인에 부하가 거의 안 간다. 대신 대가로 조용히 메모리를 수 GB씩 먹고, 숨은 O(n) 스캔을 돌리고, stale read(오래된 값 읽기)에 걸려 넘어진다.

이 트레이드오프를 이해하고 있느냐 아니냐가 실서비스에서 컨트롤러 굴려본 사람과 예제만 돌려본 사람의 차이다.

2. 핵심: 캐시가 실제로 어떻게 채워지고 읽히는가

한 줄 요약부터

reconcile 안의 r.Get(), r.List()는 API 서버를 안 읽는다. 매니저가 시작할 때 list로 워밍업한 뒤 watch로 계속 최신 상태를 유지하는 로컬 캐시에서 읽는다. 나머지 성질들은 전부 이 한 줄에서 파생된다.

• 읽기는 싸다. 하지만 쓰기 직후 강한 일관성(strong consistency)은 보장 안 된다.
• 쓰기는 캐시를 우회해서 API 서버로 직행한다.
• 캐시 크기와 인덱스 개수가 곧 메모리 사용량이다.
• 잘못 짠 List()는 수만 개 오브젝트에 대한 선형 스캔으로 조용히 변한다.

파이프라인: API 서버에서 이벤트 핸들러까지

sigs.k8s.io/controller-runtime/pkg/cache는 사실 k8s.io/client-go/tools/cache를 얇게 감싼 것뿐이다. Kubernetes 전체를 굴리는 것과 똑같은 프리미티브가 밑에 깔려 있다.

API 서버
   │  (list 1회 + watch 지속)
   ▼
Reflector      ← API 서버와 직접 대화하는 유일한 컴포넌트
   │  (delta 스트림)
   ▼
DeltaFIFO      ← key별로 변경 이력을 순서대로 누적
   │  (Pop)
   ▼
Indexer(Store) ← 실제 오브젝트가 사는 인메모리 저장소 + 인덱스
   │
   ▼
Event Handlers ← 당신 컨트롤러가 여기 붙는다 (OnAdd/OnUpdate/OnDelete)

각 링크를 실무자 관점으로 풀어보면:

Reflector는 시작할 때 딱 한 번 list를 친다. API 서버는 오브젝트 목록과 함께 그 스냅샷이 찍힌 시점의 resourceVersion을 돌려준다. 그러면 Reflector가 "버전 X부터 watch 열어줘"라고 요청하고, 그 이후에 일어난 모든 이벤트 스트림을 받는다. list와 watch 사이에 이벤트가 새는 위험이 없는 이유가 이거다. watch가 list가 끝난 지점에서 정확히 이어붙는다.

연결이 끊기면 마지막으로 알던 resourceVersion으로 재연결한다. API 서버가 410 Gone("그 버전은 이미 히스토리에서 밀려났어, 너무 뒤처졌어")을 돌려주면 그때 fresh list를 다시 친다. 이걸 relist라고 하는데, 스케줄로 도는 게 아니라 이런 실패 시나리오에서만 발생한다. "주기적으로 API 서버 긁는 거 아니냐"는 오해가 여기서 깨진다.

DeltaFIFO는 Reflector와 informer 사이의 버퍼다. 세 가지를 해결한다:

• 순서 보존: default/my-deploy에 대해 흘러온 변경 순서를 소비자도 똑같이 본다.
• key별 그룹핑: 같은 namespace/name의 delta가 한 슬롯에 쌓인다. Pop()은 delta 하나가 아니라 마지막 호출 이후 그 key에 쌓인 delta 전체를 슬라이스로 돌려준다.
• 선택적 중복 제거: 연속된 Deleted delta는 합친다. 근데 연속된 Added나 Updated는 안 합친다. 중간 상태를 최종 하나로 뭉개는 건 원칙적으로 DeltaFIFO의 일이 아니다.

비유하자면

Git으로 생각하면 편하다. Reflector가 git fetch로 원격 변경을 계속 당겨오고, Indexer는 로컬 워킹 카피다. 당신의 r.Get()은 로컬 파일을 읽는 것이지 매번 GitHub에 요청 날리는 게 아니다. 그래서 빠르지만, 방금 push한(=Update한) 내용이 아직 fetch되기 전이면 로컬에선 옛날 상태가 보인다. 이게 stale read의 정체다.

3. 실무 관점: 트레이드오프와 흔한 함정

함정 1: Update 직후 Get 하면 옛날 값이 나온다

가장 흔하고 가장 오래 헤매는 케이스다. 쓰기는 API 서버로 직행하지만, 그 변경이 watch를 타고 로컬 캐시에 반영되기까지는 시간이 걸린다. 코드로 보면:

func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var cm corev1.ConfigMap
    if err := r.Get(ctx, req.NamespacedName, &cm); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    cm.Data["updated"] = "true"
    if err := r.Update(ctx, &cm); err != nil {   // API 서버로 직행
        return ctrl.Result{}, err
    }

    // 함정: 여기서 다시 Get 하면 캐시에서 읽으므로
    // 방금 쓴 값이 아직 안 보일 수 있다
    var again corev1.ConfigMap
    _ = r.Get(ctx, req.NamespacedName, &again)
    // again.Data["updated"] 가 "true"가 아닐 수 있음!

    return ctrl.Result{}, nil
}

여기서 "그럼 재조회해서 값 맞을 때까지 루프 돌리자"는 최악의 대응이다. 캐시가 갱신될 때까지 busy loop를 도는 순간 CPU를 태운다. 올바른 접근은 reconcile을 멱등하게(idempotent) 짜는 것이다. Update 직후 재조회에 의존하지 말고, 다음 reconcile에서 다시 원하는 상태로 맞추면 된다. watch가 변경을 감지해서 어차피 다시 큐에 넣어준다.

정말로 방금 쓴 최신 값을 즉시 읽어야 하는 예외적 상황(예: optimistic lock 충돌 재시도, 상태 머신에서 순서가 중요한 경우)에서만 APIReader를 쓴다. 이건 캐시를 우회해서 API 서버를 직접 읽는다. 대신 값이 비싸니 남발하면 처음에 캐시 만든 의미가 없어진다.

// 캐시 우회 직접 읽기 - 정말 필요할 때만
if err := r.APIReader.Get(ctx, req.NamespacedName, &cm); err != nil {
    return ctrl.Result{}, err
}

함정 2: RBAC 누락 → 캐시 워밍업 자체가 실패

이건 검색으로 제일 많이 유입되는 에러다. 새 타입을 watch에 등록했는데 ServiceAccount에 해당 리소스 list/watch 권한이 없으면, informer가 캐시를 못 채우고 시작 단계에서 이런 로그가 뜬다:

W0729 10:23:41.882314   1 reflector.go:539] pkg/mod/k8s.io/client-go/tools/cache/reflector.go:229:
  failed to list *v1.ConfigMap: configmaps is forbidden:
  User "system:serviceaccount:my-ns:my-controller" cannot list resource "configmaps"
  in API group "" at the cluster scope

E0729 10:23:41.882390   1 reflector.go:147] pkg/mod/k8s.io/client-go/tools/cache/reflector.go:229:
  Failed to watch *v1.ConfigMap: failed to list *v1.ConfigMap: configmaps is forbidden

핵심 포인트: 컨트롤러는 크래시하지 않고 이 로그만 계속 토해낸다. Reconcile은 호출되긴 하는데 캐시가 비어 있어서 r.Get()이 NotFound를 돌려주고, 왜 아무 일도 안 일어나는지 한참 헤매게 된다. 로그를 안 보면 진짜 잡기 어렵다.

kubebuilder를 쓴다면 리컨사일러 위에 marker 주석을 달고 make manifests로 RBAC를 재생성하는 게 정석이다:

//+kubebuilder:rbac:groups="",resources=configmaps,verbs=get;list;watch;create;update;patch;delete

여기서 list와 watch가 빠지면 캐시가 안 채워진다. get만 있어도 informer 워밍업은 실패한다는 걸 기억하자.

함정 3: List()가 조용히 선형 스캔으로 변한다

필드 셀렉터로 필터링한다고 생각하고 짠 List()가 인덱스가 없으면 전체 스토어를 훑는 O(n) 스캔이 된다. 오브젝트 수천 개까진 티도 안 나다가, 수만 개 규모에서 reconcile 지연이 확 늘어난다. 특정 필드로 자주 조회한다면 매니저 셋업 시점에 인덱서를 미리 등록하자:

// main.go 또는 SetupWithManager 근처
err := mgr.GetFieldIndexer().IndexField(
    ctx, &corev1.Pod{}, "spec.nodeName",
    func(o client.Object) []string {
        pod := o.(*corev1.Pod)
        return []string{pod.Spec.NodeName}
    },
)
if err != nil {
    return err
}

// 이후 이렇게 조회하면 인덱스를 탄다
var pods corev1.PodList
err = r.List(ctx, &pods,
    client.MatchingFields{"spec.nodeName": "node-1"},
)

인덱스 없이 client.MatchingFields를 쓰면 에러가 나거나(등록 안 된 필드일 때) 전체 스캔으로 떨어진다. 자주 쓰는 조회 패턴은 반드시 인덱스로 뒷받침해야 한다.

함정 4: 캐시 스코프를 안 좁혀서 메모리 폭발

기본값은 클러스터 전체의 해당 타입을 전부 캐시에 올린다. Secret이나 ConfigMap처럼 개수가 많은 리소스를 무심코 watch하면 메모리가 순식간에 GB 단위로 뛴다. 특히 대규모 클러스터에서 Pod 전체를 캐시하면 OOMKilled로 재시작 루프에 빠지기도 한다.

매니저 생성 시 캐시 범위를 좁히자. 특정 네임스페이스만, 혹은 특정 라벨만:

mgr, err := ctrl.NewManager(cfg, ctrl.Options{
    Cache: cache.Options{
        // 특정 네임스페이스로 제한
        DefaultNamespaces: map[string]cache.Config{
            "my-ns": {},
        },
        // 타입별로 필터를 다르게
        ByObject: map[client.Object]cache.ByObject{
            &corev1.Secret{}: {
                Label: labels.SelectorFromSet(labels.Set{
                    "managed-by": "my-controller",
                }),
            },
        },
    },
})

이렇게 ByObject로 라벨 셀렉터를 걸면 애초에 캐시에 안 올라온다. 다만 셀렉터에 안 걸린 오브젝트는 캐시에서 안 보이므로, 그걸 r.Get()하면 NotFound가 난다는 점을 팀에 공유해야 한다. 스코프 좁히기와 "필요한 걸 못 읽는 버그"는 종이 한 장 차이다.

확인 명령어: watch가 어떻게 도는지 눈으로 보기

컨트롤러가 소비하는 것과 같은 이벤트 스트림을 kubectl로도 볼 수 있다. 이걸 한번 돌려보면 "단일 최종 오브젝트가 아니라 상태의 연쇄"라는 감이 온다:

$ kubectl get pods --watch
NAME          READY   STATUS              RESTARTS   AGE
my-pod        0/1     Pending             0          0s
my-pod        0/1     ContainerCreating   0          1s
my-pod        0/1     Running             0          4s
my-pod        1/1     Running             0          8s

스케줄러가 노드를 배정하고, kubelet이 status를 갱신하고, 여러 컨트롤러가 각자 변경을 얹으면서 한 오브젝트가 여러 상태를 거쳐 간다. 컨트롤러도 정확히 이 스트림을 받아서 로컬 캐시를 최신으로 유지한다.

4. 정리

한 줄 요약: reconcile 안의 읽기는 API 서버가 아니라 list+watch로 채운 로컬 인메모리 캐시에서 나온다. 그래서 읽기는 싸지만 쓰기 직후 강한 일관성이 없고, 캐시 크기·인덱스가 곧 메모리이며, 잘못된 List는 조용히 선형 스캔이 된다.

누가 언제 신경 써야 하나:

• 이미 controller-runtime으로 컨트롤러를 짜고 있고, "왜 방금 쓴 값이 안 보이지?"를 겪은 사람 → 함정 1을 멱등 설계로 해결하라.
• 대규모 클러스터(오브젝트 수만 개 이상)에 컨트롤러를 배포할 사람 → 함정 3, 4를 배포 전에 반드시 점검하라. 메모리와 reconcile 지연이 걸린다.
• 새 CRD/리소스를 watch에 추가하는 사람 → RBAC의 list/watch부터 확인하라. 함정 2는 크래시 없이 조용히 아무것도 안 하게 만든다.

반대로 소규모 클러스터에서 몇 개 오브젝트만 다루는 컨트롤러라면 기본값으로도 충분하다. 캐시 커스터마이징은 실제로 메모리나 일관성 문제를 겪은 뒤에 손대도 늦지 않다. 다만 멘탈 모델만큼은 처음부터 정확히 갖고 있어야 프로덕션에서 비싼 놀라움을 피한다.

참고 자료

• How the controller-runtime Cache Actually Works, and Why Your Controller Does Not Crash the API Server (Kubernetes 공식 블로그, 원문)
• controller-runtime pkg/cache 문서 (pkg.go.dev)
• client-go tools/cache 문서 (Reflector, DeltaFIFO, Indexer)
• Kubernetes API 개념: watch와 resourceVersion, watch bookmark
• The Kubebuilder Book (RBAC marker, SetupWithManager 등)