ycra.dev | Blog

StarRocks Operator는 왜 클러스터가 많아지면 멈추는가

Mon, 29 Jun 2026 00:00:00 GMT

문제: CR이 늘어나자 Operator가 멈췄다

StarRocks Kubernetes Operator는 StarRocksCluster라는 CR(Custom Resource) 하나하나를 watch하면서, 그 안에 정의된 FE(Frontend)·CN(Compute Node)·BE(Backend) 컴포넌트를 실제 클러스터 상태와 맞추는(reconcile) 역할을 한다.

문제는 이 Operator가 단일 클러스터, 혹은 소수의 클러스터를 관리하는 것을 전제로 설계되었다는 점이다. CR이 한두 개일 때는 아무 문제가 없다. 그런데 하나의 클러스터 위에 수십 개의 StarRocks 클러스터(CR) 가 떠 있는 멀티테넌트 환경으로 가면 이야기가 달라진다.

CR이 특정 개수를 넘어서면서 Operator가 다음과 같은 증상을 보이기 시작했다.

새 CR을 만들어도 한참 동안 reconcile이 시작되지 않는다.
스펙을 바꿔도 반영이 지연된다.
결국 Operator가 사실상 hang에 빠진 것처럼 보인다.

원인을 추적해보니, 코드에 하드코딩된 controller-runtime 설정값 세 가지가 맞물려 있었다.

왜 멈추는가: 세 가지 병목

1. reconcile 동시성이 1로 고정돼 있다

controller-runtime의 컨트롤러는 내부적으로 workqueue에서 CR의 key를 꺼내 reconcile하는 워커 goroutine을 돌린다. 이 워커 수가 바로 MaxConcurrentReconciles이고, 기본값은 1이다.

즉, 아무리 CR이 많아도 한 번에 단 하나의 CR만 reconcile된다. 나머지는 모두 큐에서 순서를 기다린다.

reconcile 하나가 가벼우면 워커 1개로도 충분하다. 하지만 StarRocks의 reconcile은 가볍지 않다. CR 하나마다 FE/CN/BE 각각의 StatefulSet·Service·ConfigMap 상태를 확인하고, 필요하면 API 서버에 갱신 요청을 보낸다. CR 하나를 처리하는 데 걸리는 시간 × 큐에 쌓인 CR 수만큼 선형으로 지연이 누적된다.

2. 2분마다 전체 CR이 다시 큐에 들어온다 (resync)

controller-runtime 매니저에는 SyncPeriod라는 설정이 있고, StarRocks Operator는 이를 2분으로 잡고 있었다.

이전 글에서 정리했듯, resync는 API 서버를 다시 조회하는 게 아니다. 로컬 캐시에 있는 모든 객체를 핸들러에 다시 흘려보내 reconcile을 한 번 더 돌리는 안전장치다. 문제는 이게 전체 CR을 대상으로 한다는 것이다.

CR이 50개라면, 2분마다 50개의 reconcile 요청이 한꺼번에 큐에 들어온다. 그런데 (1)에서 봤듯 워커는 1개뿐이다. 한 번의 resync 사이클(50개 reconcile)을 2분 안에 못 끝내면, 다음 resync가 또 50개를 밀어 넣는다. 큐는 줄지 않고 계속 불어나고, Operator는 영원히 밀린 일을 따라잡지 못한다.

3. 클라이언트 rate limit(QPS/Burst)에 막힌다

설령 워커를 늘려 동시 처리를 한다 해도, 그 모든 reconcile은 결국 Kubernetes API 서버로의 호출로 이어진다. controller-runtime의 client-go 클라이언트에는 클라이언트 측 rate limiter가 걸려 있다.

QPS: 초당 허용 요청 수 (controller-runtime 기본 20)
Burst: 순간적으로 허용하는 버스트 (기본 30)

CR이 많아 동시에 쏟아지는 API 호출이 이 한도를 넘으면, client-go는 요청을 클라이언트 쪽에서 큐잉하며 의도적으로 지연시킨다. 로그에는 client-side throttling 경고가 찍히고, reconcile은 또 한 번 느려진다. 동시성을 올려도 QPS/Burst가 그대로면 이 벽에 막힌다.

종합: 세 값이 서로를 악화시킨다

세 병목은 독립적이지 않다.

동시성 1 → reconcile 처리 속도가 낮다
2분 resync → 그 느린 처리량에 주기적으로 전체 CR을 다시 얹는다
QPS/Burst 20/30 → 처리 속도를 올리려 해도 API 호출 단계에서 다시 막힌다

CR이 적을 때는 한 사이클을 2분 안에 여유롭게 끝내므로 셋 다 문제가 안 된다. 하지만 CR 수가 임계점을 넘는 순간, 큐가 발산하면서 Operator 전체가 멈춘 것처럼 보이게 된다.

해결: 하드코딩 값을 Helm으로 끄집어내다 (PR #769)

근본 원인이 환경에 맞지 않는 고정값이라면, 답은 그 값을 운영자가 환경에 맞게 조절할 수 있게 만드는 것이다. PR #769은 이 세 가지(+α) 설정을 Operator 플래그로 노출하고, 다시 Helm 차트 값으로 끌어올렸다. 이제 이미지 재빌드 없이 values만 바꿔 튜닝할 수 있다.

노출된 설정은 다음과 같다.

플래그	의미	기본값	비고
`--max-concurrent-reconciles`	동시에 도는 reconcile 워커 수	`1`	올리면 병렬 처리
`--sync-period`	주기적 resync 간격	`2m`	늘리면 주기적 부하 감소
`--kube-api-qps`	클라이언트 초당 요청 한도	`0` → controller-runtime 기본 `20`	0이면 인자 자체를 생략
`--kube-api-burst`	클라이언트 버스트 한도	`0` → controller-runtime 기본 `30`	0이면 인자 자체를 생략

# values.yaml — starrocksOperator 하위
starrocksOperator:
  # CR이 많은 환경에서 병렬 처리량을 늘린다
  maxConcurrentReconciles: 5
  # 주기적 전체 reconcile 부하를 줄인다
  syncPeriod: "10m"
  # API 호출 한도를 환경에 맞게 상향
  kubeApiQps: 50
  kubeApiBurst: 100

하위 호환성

설계에서 신경 쓴 부분은 기존 사용자가 아무것도 안 해도 동작이 똑같아야 한다는 것이다.

모든 기본값은 기존 하드코딩 값과 동일하다 (max-concurrent-reconciles=1, sync-period=2m).
kube-api-qps/kube-api-burst는 기본값 0일 때 플래그 자체를 전달하지 않아, controller-runtime의 원래 기본값(20/30)이 그대로 적용된다.
따라서 Helm 차트를 다시 렌더링하지 않고 Operator 이미지만 올려도 안전하다.

부모 차트(kube-starrocks)의 values는 scripts/create-parent-chart-values.sh로 서브차트 값에서 재생성된다.

실험: 세 값은 정말 부하를 좌우하는가

설정을 노출했으니, 각 값이 실제로 부하를 얼마나 좌우하는지 측정했다. 이 문제는 특히 API 서버 응답이 간헐적으로 느려지는 환경에서 두드러졌으므로, 핵심 질문을 이렇게 잡았다 — “API에 지연이 끼고 CR이 여러 개일 때, 이 세 값이 클러스터 생성 시간과 상시 트래픽을 얼마나 바꾸는가?”

실험 환경

빠른 반복 검증을 위해 envtest(실제 kube-apiserver + etcd를 띄우되 노드·kubelet은 없는 경량 환경) 위에서 Operator를 구동하고, Operator → API 서버 경로의 병목만 측정했다. 실제 환경의 API 지연은 프록시(toxiproxy)로 RTT를 인위 주입해 재현했다.

항목	값
측정 방식	`envtest` — 실제 kube-apiserver + etcd, 노드/kubelet 없음
측정 대상	StarRocks Operator(`kube-starrocks`) → kube-apiserver 호출
API 지연 재현	toxiproxy로 Operator↔apiserver 양방향 RTT 주입
비교 축	패치 전(기본값) ↔ 패치 후(동시성·QPS·sync-period 상향)

⚠️ 측정 범위 주의 — 아래 수치는 “하한선”이다. envtest엔 kubelet이 없어 StatefulSet을 만들어도 Pod가 안 뜬다. 그래서 Operator는 FE의 StatefulSet·Service를 만든 뒤 “FE Pod Ready 대기”에서 멈추고, CN·BE는 아예 실행되지 않는다. 즉 측정값은 CR 1건이 유발하는 전체 API 호출 중 FE 단계까지만 잡힌다. 실제 환경에선 CN·BE까지 떠서 호출·resync가 곱으로 늘어나므로, 여기서 보이는 개선폭은 실제로는 더 크게 나타날 바닥값으로 읽어야 한다.

출발점 — CR 하나가 API를 얼마나 두드리나

먼저 부하의 단위를 쟀다. CR 1개를 만들고 30초간 API audit 로그를 세어보니, FE 생성까지만 12회의 호출이 찍혔다. service·statefulset마다 create·update·patch가 반복되고, status 서브리소스 패치만 3회다. 여기서 전체 컴포넌트(FE+CN+BE+FE-proxy)로 환산하면 CR 1건당 약 30회. CR이 수십 개면 이 호출이 곱으로 쌓인다 — 모든 부하의 출발점이다.

노브 1 — `max-concurrent-reconciles`: 직렬 처리가 API 지연을 만나면 터진다

기본값 1은 CR을 한 건씩 순차 처리한다. 평소엔 티가 안 나지만, API 왕복이 느려지는 순간 직렬 처리는 재앙이 된다. CR 50개를 만들되 RTT 100ms(왕복 200ms)를 주입한 결과:

조건	완료 시간	CR당 평균
기본값 (동시성 1)	41.1s	822 ms
패치 (동시성 50 + QPS 상향)	0.22s	4.4 ms

xychart-beta
  title "동시성 1→50 — RTT 100ms·CR 50개 생성 완료 시간 (초)"
  x-axis ["기본값 (동시성 1)", "패치 (동시성 50)"]
  y-axis "완료 시간 (초)" 0 --> 45
  bar [41.1, 0.22]

기본값은 CR을 한 건씩 처리하며 호출마다 왕복 200ms가 누적돼 41초가 걸렸다. 동시성을 50으로 풀자 50개 CR의 호출이 거의 동시에 나가고 HTTP/2 multiplexing이 받쳐주며 0.22초 — 약 187배 단축됐다. 직렬 병목 자체보다, 그게 RTT와 곱해질 때 폭발한다는 게 핵심이다.

RTT가 없는 환경(CR 100개)에서도 효과는 있지만 결이 다르다:

조건	완료 시간	throttling
기본값	8.9s	0
동시성 50만	5.99s	1회
전체 패치	0.60s	0

RTT가 없어도 동시성만 올리면 8.9s→5.99s로 1.5배 빨라진다. 그런데 이번엔 throttling이 1회 떴다 — 동시 호출을 늘리니 이번엔 QPS 상한(20)에 걸리기 시작한 것이다. 그래서 다음 노브가 따라와야 한다.

노브 2 — `kube-api-qps`/`burst`: 동시성을 올리면 반드시 같이 올려야 한다

동시성을 50으로 키워 호출을 한꺼번에 쏟으면, client-go의 클라이언트 측 rate limiter(QPS=20/Burst=30)에 걸려 스스로 요청을 지연시키는 self-throttling이 발생한다.

조건	throttling 이벤트
동시성 50, QPS 기본(20)	1회
동시성 50, QPS 100	0회

QPS/Burst를 100/200으로 올리자 throttling이 사라졌다. 즉 QPS는 단독 레버가 아니라 동시성 상향의 짝이다 — 워커만 늘리고 QPS를 그대로 두면 늘린 만큼 클라이언트 큐에서 다시 막힌다. FE만 뜨는 이 환경에서도 1회 관측됐으니, CN까지 뜨는 실제 환경에선 빈도가 더 높다.

노브 3 — `sync-period`: 가만히 있어도 깔리는 상시 부하

앞 두 노브가 “생성하는 순간”의 부하라면, sync-period는 아무것도 안 바뀌어도 주기적으로 깔리는 상시 트래픽을 좌우한다. CR 100개를 만든 뒤 5분간 초당 API 호출율을 쟀다:

조건	5분간 이벤트	평균 req/s
기본값 (sync-period 2m)	345	1.15
패치 (sync-period 30m)	95	0.32

xychart-beta
  title "sync-period 2m→30m — CR 100개 상시 트래픽 (평균 req/s)"
  x-axis ["sync 2m (기본)", "sync 30m (패치)"]
  y-axis "평균 req/s" 0 --> 1.3
  bar [1.15, 0.32]

resync 주기를 2분→30분으로 늘리자 상시 트래픽이 약 1/4로 줄었다. 이 트래픽의 대부분은 상태가 안 바뀐 CR을 다시 도는 것 — 순수한 낭비다. 그리고 이 환경은 FE만 떠서 이벤트가 적은데도 이 정도다. CN이 다수 뜨는 실제 환경에선 resync 대상이 훨씬 많아 상시 부하가 곱으로 커지고, 그만큼 주기를 늘리는 효과도 커진다.

종합 해석

노브	무엇을 바꾸나	검증된 효과
`max-concurrent-reconciles` 1 → 50	직렬 → 병렬 처리	RTT 100ms·CR 50개에서 41.1s → 0.22s. API가 느릴수록 효과가 폭발
`kube-api-qps`/`burst` 20/30 → 100/200	클라이언트 rate limit 완화	동시성 상향 시 생기는 self-throttling 1회 → 0회. 동시성의 필수 짝
`sync-period` 2m → 30m	주기적 resync 간격	상시 트래픽 1.15 → 0.32 req/s (≈1/4). 변경 없는 CR의 낭비 reconcile 감소

세 값 모두 환경에 따라 정답이 다르다 — API가 느린지, CR이 몇 개인지, drift 보정이 얼마나 급한지에 따라. 그래서 코드에 박지 않고 Helm으로 노출한 것이 옳았다.

정리

StarRocks Operator는 소수 CR을 전제로 설계되어, controller-runtime의 동시성(1)·resync(2분)·rate limit(20/30)이 하드코딩돼 있었다.
이 고정값들은 CR이 적을 땐 무해하지만, 다수 클러스터 환경에서 큐가 발산하며 Operator를 hang에 빠뜨린다.
PR #769은 이 값들을 플래그·Helm values로 노출해 이미지 재빌드 없이 환경에 맞게 튜닝할 수 있게 했고, 기본값은 그대로 둬 하위 호환성을 지켰다.
envtest에 RTT를 주입해 패치 전후를 측정한 결과: 동시성 1→50은 RTT 100ms·CR 50개 환경에서 생성 시간을 41.1s → 0.22s로 줄였고, sync-period 2m→30m은 상시 트래픽을 약 1/4(1.15→0.32 req/s)로 낮췄으며, kube-api-qps 상향은 동시성을 올릴 때 따라붙는 self-throttling(1회→0회)을 제거했다.

결국 이 작업의 핵심은 새로운 기능이 아니라 “환경에 따라 달라야 하는 값을 코드에 박아두지 마라” 는 원칙이다. Operator처럼 다양한 규모에서 돌아야 하는 컨트롤러일수록, 동시성·주기·rate limit 같은 운영 파라미터는 운영자의 손에 쥐여주는 것이 옳다.

Kubernetes Informer는 어떻게 동작하는가

Sun, 21 Jun 2026 00:00:00 GMT

watch를 직접 걸 때 마주치는 것들

Kubernetes 위에서 동작하는 컨트롤러를 만들 때, 가장 먼저 부딪히는 문제는 “리소스 변화를 어떻게 감지할 것인가” 다. 가장 단순한 답은 API 서버에 직접 watch를 거는 것이다. Java의 fabric8 클라이언트를 사용한다면 이렇게 watch를 걸 수 있다.

// API 서버에 직접 watch 연결 — 이벤트 스트림을 그대로 받는다
client.pods().inNamespace("default").watch(new Watcher<Pod>() {
    @Override
    public void eventReceived(Action action, Pod pod) {
        // ADDED / MODIFIED / DELETED 이벤트가 올 때마다 호출
        reconcile(pod);
    }
    @Override
    public void onClose(WatcherException e) {
        // 연결이 끊기면 직접 재연결 로직을 구현해야 한다
    }
});

직접 watch를 걸면 event를 수신할 수는 있지만 여러가지 복잡한 문제를 겪게 된다.

연결이 끊기면 직접 복구해야 한다. watch는 장시간 유지되는 HTTP 스트림이라 네트워크·재시작 등으로 끊긴다. 끊기면 마지막 resourceVersion부터 다시 watch를 걸어야 하고, 그 버전이 너무 오래돼 410 Gone이 오면 전체를 다시 List한 뒤 watch를 재개해야 한다.
로컬 상태가 없다. “지금 이 네임스페이스의 Pod 전체”가 필요하면 또 API 서버에 List를 날려야 한다. 캐시가 없으니 읽을 때마다 API 서버에 부담이 간다.
컴포넌트마다 watch가 늘어난다. 컨트롤러 A, B, C가 각자 Pod를 본다면 watch 연결도 3개다. 같은 데이터를 세 번 받는다.

Informer는 바로 이 반복되는 문제들 — 재연결, 재동기화, 로컬 캐시, 연결 공유 — 를 한 번에 정리해 주는 패턴이다. fabric8에도 client-go를 본떠 만든 SharedIndexInformer가 있다.

SharedInformerFactory factory = client.informers();
SharedIndexInformer<Pod> informer =
    factory.sharedIndexInformerFor(Pod.class, 30_000L); // resync 주기 30s

informer.addEventHandler(new ResourceEventHandler<Pod>() {
    public void onAdd(Pod pod) { reconcile(pod); }
    public void onUpdate(Pod oldPod, Pod newPod) { reconcile(newPod); }
    public void onDelete(Pod pod, boolean finalStateUnknown) { cleanup(pod); }
});

factory.startAllRegisteredInformers();

// 읽기는 API 서버가 아니라 로컬 캐시에서
Lister<Pod> lister = new Lister<>(informer.getIndexer(), "default");
List<Pod> pods = lister.list();

겉보기엔 “이벤트 핸들러 등록”이 전부지만, 그 아래에서는 꽤 정교한 매커니즘이 돌아간다. 이제 그 내부를 파헤쳐 보자. (이하 구조는 client-go 기준이며, fabric8 informer도 동일한 모델을 따른다.)

Informer는 어떻게 동작하는가

Informer의 핵심은 “한 번 전체를 받아오고(List), 그 뒤로는 변화만 따라간다(Watch)”, 그리고 그 결과를 로컬 캐시에 항상 최신으로 유지한다는 것이다. 내부는 크게 네 개의 컴포넌트로 구성된다.

List + Watch: 한 번 받아오고, 변화만 따라간다

가장 안쪽에는 Reflector가 있다. Reflector가 하는 일은 두 단계다.

List — 대상 리소스 전체를 한 번 조회하고, 응답에 담긴 resourceVersion(그 시점의 스냅샷 버전)을 기억한다.
Watch — 그 resourceVersion부터 watch를 걸어, 이후 발생하는 변화 이벤트만 스트림으로 받는다.

연결이 끊기거나 410 Gone이 오면 Reflector가 알아서 다시 List → Watch를 수행한다. 앞서 직접 짜야 했던 재연결·재동기화 로직이 여기 들어 있는 것이다.

Reflector → DeltaFIFO → Indexer

Reflector가 받은 변화는 곧장 핸들러로 가지 않고 DeltaFIFO라는 큐를 거친다. DeltaFIFO는 객체(key)별로 변화(delta)를 순서대로 쌓아두는 큐다. 같은 객체에 여러 변화가 빠르게 일어나도 순서가 보장되고, 짧은 시간의 중복 이벤트를 합쳐 처리할 수 있다.

큐에 쌓인 delta는 Informer의 컨트롤러 루프가 하나씩 꺼내(Pop) 두 가지 일을 한다.

Indexer(로컬 캐시)를 갱신 — Added/Updated면 저장, Deleted면 제거.
이벤트 핸들러 호출 — 등록된 ResourceEventHandler(OnAdd/OnUpdate/OnDelete)에 변화를 전달.

여기서 중요한 순서가 있다. 캐시를 먼저 갱신한 뒤 핸들러를 부른다. 그래서 핸들러 안에서 Lister로 캐시를 읽으면, 방금 들어온 변화가 이미 반영된 상태를 볼 수 있다.

Indexer와 Lister: 읽기는 캐시에서

Indexer는 단순한 key-value 저장소(ThreadSafeStore)에 인덱스를 더한 것이다. 네임스페이스별, 레이블별처럼 자주 쓰는 기준으로 객체를 빠르게 찾도록 색인을 만들어 둔다.

컨트롤러가 “현재 상태”를 읽을 때 쓰는 Lister는 이 Indexer를 감싼 읽기 전용 뷰다. 즉 lister.list()나 lister.get(name)은 API 서버가 아니라 메모리에서 응답한다. 직접 watch를 쓸 때 “전체가 필요하면 또 List를 날려야 했던” 문제를 해결한다.

또 Informer는 주기적으로 resync를 수행하는데, 이때도 API 서버를 부르지 않는다. 로컬 캐시에 있는 객체들에 대해 Sync delta를 다시 흘려보내 핸들러를 한 번씩 더 호출할 뿐이다. “혹시 놓친 reconcile이 있으면 다시 맞춰라”는 안전장치이고, 비용은 전부 로컬에서 치른다.

SharedInformer: 하나의 watch를 나눠 쓴다

마지막 조각이 SharedInformer다. 같은 리소스(예: Pod)를 여러 컨트롤러가 본다면, informer를 각자 만들 필요 없이 하나의 informer(= 하나의 List+Watch, 하나의 캐시)를 공유하고, 이벤트만 각 리스너에게 나눠준다.

앞의 “컨트롤러마다 watch 3개” 그림과 비교하면 차이가 분명하다. 연결도 1개, 캐시도 1개이다.

Informer가 API 서버 부하를 줄이는 원리

정리하면 Informer가 API 서버 부하를 줄이는 방식은 세 가지다.

폴링이 아니라 List 1회 + Watch 스트림. 초기 한 번만 전체를 받고, 그 뒤로는 변화분만 흘러온다. “1초마다 전체 List”같은 폴링 트래픽이 사라진다.
읽기는 전부 로컬 캐시(Lister). reconcile 도중 현재 상태를 아무리 자주 조회해도 API 호출은 0이다.
SharedInformer로 연결·캐시 공유. 한 리소스를 N개 컨트롤러가 봐도 watch는 1개다. resync도 로컬이라 추가 호출이 없다.

결과적으로 클러스터에 컨트롤러가 수십 개 떠 있어도, API 서버 입장에서는 리소스 종류별 watch 몇 개만 감당하면 된다.

API 서버의 watch cache가 etcd 부하를 줄이는 원리

여기서 한 단계 더 내려가 보자. 컨트롤러들의 watch를 API 서버가 받아주는 건 알겠는데, 그 API 서버는 etcd를 어떻게 감당할까?

만약 API 서버가 클라이언트 watch 하나하나를 그대로 etcd watch로 옮겼다면, 클라이언트가 1000개면 etcd watch도 1000개가 됐을 것이다. 실제로는 그렇지 않다. API 서버 내부에는 watch cache(cacher) 라는, Informer와 똑 닮은 구조가 들어 있기 때문이다.

API 서버는 리소스 종류별로 etcd에 watch를 단 하나 건다(storage layer의 cacher).
그 이벤트를 메모리의 watch cache(최근 이벤트 링 버퍼 + 현재 상태 저장소) 에 쌓는다.
모든 클라이언트 watch는 etcd가 아니라 이 watch cache가 직접 서빙한다.
게다가 resourceVersion=0 같은 List 요청은 etcd 쿼럼 읽기 대신 watch cache에서 응답할 수 있어, 읽기 부하까지 줄인다.

즉 API 서버 안에도 “Reflector → 캐시 → 다수의 watcher에게 분배”라는 Informer와 동일한 fan-in 패턴이 한 겹 더 있는 것이다.

정리: 같은 패턴이 계층으로 쌓인다

처음의 질문 — “리소스 변화를 어떻게 감지할 것인가” — 에 대한 Kubernetes의 답은 결국 계층적 캐싱이다. 같은 List+Watch 패턴이 두 겹으로 포개져 있다.

컨트롤러 ↔ Informer: 수많은 reconcile의 읽기를 로컬 캐시가 받아내고, API 서버에는 watch 1개만 남긴다.
Informer ↔ API 서버 watch cache: 수많은 클라이언트 watch를 watch cache가 받아내고, etcd에는 watch 1개만 남긴다.

각 계층이 위층의 watch를 fan-in으로 합쳐 아래층 부하를 줄인다. 직접 watch를 걸던 처음 코드에서 떠안아야 했던 재연결·캐시·연결 공유 문제는, 사실 Kubernetes가 클러스터 전체 규모에서 이미 풀어둔 문제였던 셈이다.

Kubernetes Informer를 쓸 때 주의할 점

Sun, 21 Jun 2026 00:00:00 GMT

이전 글에서는 Informer가 List+Watch와 로컬 캐시로 어떻게 API 서버, etcd 부하를 줄이는지 살펴보았다. 그런데 Informer를 사용할 때 주의할 점이 있다. Informer는 “이렇게 써야만 안전하다”는 몇 가지 가정을 포함하고 있다. 그 가정을 간과하면 코드는 평소엔 잘 돌다가, 연결이 한 번 끊기거나 부하가 몰리는 순간에 소리 없이 어긋날 수 있다.

이 글은 Informer 기반 컨트롤러를 짤 때 틀리기 쉬운 지점들을 모아봤다.

1. 모든 이벤트를 본다고 믿지 마라 (순서·유실)

Informer는 “발생한 모든 변화 이벤트”를 보장하지 않는다.

순서는 누가 보장하나

watch 스트림의 순서는 Informer가 만드는 게 아니라 API 서버(궁극적으로 etcd) 가 보장한다. etcd는 단일 일관 로그라 모든 변경에 단조 증가하는 revision이 붙고, 이게 resourceVersion으로 노출된다. API 서버의 watch cache가 이 순서를 보존해 여러 watcher에게 똑같은 순서로 보낸다. Reflector는 받은 순서 그대로 DeltaFIFO에 넣을 뿐이다.

단, 여기서 “순서”는 단일 watch 스트림 안에서 이벤트가 도착하는 순서 그 자체를 뜻한다. 순서를 보장하는 건 스트림이지, resourceVersion 값을 비교해서 얻는 게 아니다. 서로 다른 리소스 종류(Pod와 Node 등) 사이의 이벤트 순서 역시 아무것도 보장되지 않는다.

끊긴 사이의 이벤트는 유실된다

API 서버의 watch cache는 고정 크기 링 버퍼다. watcher가 느리거나 연결이 끊겨서 재개 시 요청한 resourceVersion이 버퍼의 가장 오래된 항목보다 더 옛날이면, API 서버는 410 Gone(“too old resource version”)을 돌려준다. 그러면 Reflector는 전체를 다시 List(relist) 해서 최신 스냅샷 + 새 resourceVersion을 확보한 뒤 watch를 재개한다.

결과적으로 로컬 캐시의 정합성은 회복되지만, 두 List 사이의 개별 transition은 못 본다. 위 그림처럼 끊긴 사이에 Pod B가 생겼다 사라지면, B의 존재 자체를 통째로 놓친다.

그래서 컨트롤러는 level-triggered여야 한다

이 때문에 Informer 기반 컨트롤러의 제1원칙은 “모든 이벤트를 본다고 가정하지 마라” 다. 이벤트마다 반응하는 edge-triggered가 아니라, 관측된 현재 상태에서 desired 상태로 수렴(idempotent reconcile) 하는 level-triggered로 짜야 한다. 핸들러는 “무엇이 바뀌었나”가 아니라 “지금 상태가 어떤가”를 기준으로 동작해야 한다.

relist가 놓친 삭제를 메우는 법: tombstone

위 그림의 “set-difference로 B 삭제 감지”가 핵심이다. DeltaFIFO.Replace()는 새 List를 단순 upsert만 하지 않는다.

새 List의 key 집합을 만든다.
현재 store에는 있는데 새 List엔 없는 key(= 끊긴 사이 삭제된 것)를 찾는다.
그 key에 대해 Deleted delta를 합성하되, 삭제된 객체의 최종 상태를 모르므로 마지막으로 알던 상태를 DeletedFinalStateUnknown(통칭 tombstone)으로 감싸서 큐에 넣는다.

그래서 삭제 핸들러에 들어오는 객체는 진짜 타입이 아니라 tombstone일 수 있다. 이걸 처리 안 하면 타입 에러가 나거나 삭제가 무시될 수 있다.

func onDelete(obj interface{}) {
    pod, ok := obj.(*v1.Pod)
    if !ok {
        tombstone, ok := obj.(cache.DeletedFinalStateUnknown)
        if !ok {
            return // 알 수 없는 타입
        }
        pod, ok = tombstone.Obj.(*v1.Pod) // 마지막으로 알던 상태
        if !ok {
            return
        }
    }
    // pod의 key 정도만 신뢰 (최신 상태는 아닐 수 있음)
}

fabric8의 onDelete(Pod pod, boolean finalStateUnknown)에서 두 번째 인자 finalStateUnknown이 바로 이 tombstone 여부다. true면 “watch가 놓친 삭제를 relist로 추론한 것”이라는 신호다.

2. 캐시를 직접 수정하지 마라

Lister·Indexer가 돌려주는 객체는 캐시 안의 객체를 그대로(포인터로) 준 것이다. 복사본이 아니다.

pod, _ := lister.Pods("default").Get("my-pod")
pod.Status.Phase = "Running" // 절대 금지: 공유 캐시를 오염시킨다

이렇게 하면 다른 모든 핸들러·컨트롤러가 보는 캐시를 함께 바꿔버리고, 동시에 읽는 쪽과 data race가 난다. 수정이 필요하면 반드시 먼저 복사한다.

pod := original.DeepCopy()
pod.Status.Phase = "Running" // 복사본을 수정
client.CoreV1().Pods("default").UpdateStatus(ctx, pod, ...)

Informer 버그의 상당수가 여기서 나온다. “읽은 객체는 내 것이 아니다” 를 항상 기억하자.

3. 캐시는 항상 조금 늦다 (read-after-write)

Lister는 로컬 캐시를 읽는다. 그리고 캐시는 watch를 통해 채워지므로 etcd보다 항상 조금 뒤처져 있다. 방금 내가 Create()한 객체가 Lister에는 아직 안 보일 수 있다는 뜻이다.

이 read-after-write 불일치를 모르면 같은 리소스를 중복 생성하는 사고가 난다. Kubernetes 본체의 ReplicaSet 컨트롤러는 이를 expectations 패턴(내가 방금 만든/지운 개수를 따로 기억해 두고, 캐시가 그만큼 따라올 때까지 추가 동작을 보류)으로 보정한다. 직접 짤 때도 “캐시가 내 쓰기를 아직 못 봤을 수 있다”를 전제로 멱등하게 설계해야 한다.

4. 시작 전에 `WaitForCacheSync` 하라

초기 List가 캐시를 다 채우기 전에 reconcile을 시작하면, Lister가 빈 결과를 준다. 그러면 멀쩡히 존재하는 리소스를 “없음”으로 오판해서, 다시 만들거나 심지어 지우는 사고로 이어진다.

go informer.Run(stopCh)
if !cache.WaitForCacheSync(stopCh, informer.HasSynced) {
    return // 동기화 실패
}
// 이제부터 워커 시작

단, HasSynced는 최초 1회 동기화 완료를 알리는 게이트일 뿐이다. “지금도 최신”을 보장하지 않는다. 이후 watch가 끊겼다 relist해도 HasSynced는 계속 true다.

5. 핸들러에서 무거운 일을 하지 마라 (workqueue 패턴)

이벤트 핸들러는 key만 큐에 넣고 즉시 리턴해야 한다. 실제 작업(API 호출, 재시도, 외부 시스템 연동)은 별도 워커 goroutine에서 한다.

핸들러 안에서 동기적으로 무거운 작업을 하면, 자기 리스너 버퍼가 무한정 커지고 전체 이벤트 처리가 밀린다. workqueue를 거치면 (1) 재시도·rate-limit·backoff를 큐가 대신 해주고, (2) 같은 key의 중복 처리를 자동으로 합쳐주며(dedup), (3) 워커 수로 처리량을 조절할 수 있다. controller-runtime이 강제하는 구조가 바로 이것이다.

6. resync는 API 서버 재조회가 아니다

가장 흔한 오해. resyncPeriod를 짧게 잡으면 최신 데이터를 더 자주 받아온다고 생각하는데, 틀렸다.

resync는 로컬 캐시에 이미 있는 객체들을 핸들러에 다시 흘려보낼 뿐, 네트워크 호출이 0이다. old == new인 Update 이벤트가 다시 도는 것뿐이다. 목적은 “혹시 놓친 reconcile이 있으면 현재 상태 기준으로 한 번 더 맞춰라”는 안전장치다.

	relist	resync
트리거	watch 끊김 / `410 Gone`	`resyncPeriod` 주기
데이터 출처	API 서버 재조회	로컬 캐시
네트워크 비용	있음	없음
목적	watch 갭 복구	주기적 재조정

그래서 resync를 짧게 잡으면 데이터가 신선해지는 게 아니라 그냥 CPU만 더 탄다. 보통 0(off)이거나 수십 분 단위로 두는 게 좋다.

7. 메모리를 의식하라

Informer는 대상 타입의 객체를 전부 메모리에 캐싱한다. Pod·Secret·ConfigMap을 클러스터 전역으로 watch하면 캐시가 수 GB까지 커질 수 있다. 대응 수단:

범위를 좁혀라 — 네임스페이스 스코프 informer, label/field selector로 캐시 대상 자체를 줄인다.
TransformFunc로 잘라내라 — 저장 전에 managedFields처럼 안 쓰는 큰 필드를 떼어내 메모리를 줄인다.
초기 List 스파이크 — informer가 뜰 때 전체를 한 번에 받으면 메모리가 출렁인다. 최신 client-go의 streaming list(WatchList)는 이 초기 스파이크를 완화한다.

여러 컴포넌트가 같은 타입을 본다면 SharedInformerFactory로 informer를 공유해 캐시 중복을 막는다. 단, selector를 건 필터링 된 informer는 별도 캐시라 전체를 못 본다. “왜 내 Lister엔 이 객체가 없지?”의 단골 원인이 바로 어딘가에서 좁은 selector로 informer를 만든 경우다.

정리: Informer는 “공짜 캐시”가 아니다

Informer는 List+Watch+재연결+캐시를 대신 해주는 강력한 추상화지만, 그 대가로 몇 가지 규칙을 지킬 것을 요구한다.

이벤트는 정확하지 않다. 끊김·relist로 중간 이벤트는 유실된다 → level-triggered로 수렴하게 짜라.
읽은 객체는 내 것이 아니다. 수정 전 DeepCopy.
캐시는 조금 늦다. read-after-write를 가정하지 말고 멱등하게.
시작 전 WaitForCacheSync. 빈 캐시로 오판 금지.
핸들러는 가볍게, 일은 workqueue에서.
resync ≠ 재조회. 짧게 잡아도 신선해지지 않는다.
캐시는 메모리를 먹는다. 범위·transform·공유로 관리하라.

이 규칙들은 결국 하나로 모인다. Informer가 보여주는 건 “진실의 약간 늦은 사본”이지, 진실 그 자체가 아니다. 그 사본을 어떻게 다뤄야 하는지를 아는 것이 Informer를 제대로 쓰는 일의 전부다.

우리 팀이 Git 대충 쓰기에서 협업 시스템으로 넘어간 방법

Sun, 08 Feb 2026 00:00:00 GMT

Git을 쓰는데도 협업이 안 되는 순간들

개발자가 Git을 사용할 때는 생각보다 자주 같은 문제를 겪는다.

브랜치 전략 수립
merge 충돌 해결
commit 메시지 기준 부재로 인한 히스토리 혼란
PR 리뷰 참여 저조
히스토리 관리 실패(되돌리기 어려움, 의사결정 과정 소실)
권한/정책 운영 문제(force push, approve 기준 등)
신규 인원 온보딩 실패(적응 어려움)

우리 팀도 한동안은 이 문제들을 각자 알아서 버티는 방식으로 넘기고 있었다. 당장 기능 개발은 굴러가니까 지금은 바쁘니까 나중에 정하자로 미뤄지기 쉬웠고, 그 사이 규칙은 더 느슨해졌다. 그러다 협업이 본격적으로 필요해지는 순간, 작은 불편이 한꺼번에 터지면서 커뮤니케이션 비용이 급격히 늘어났다.

규칙이 증발한 팀에서 생긴 일

지난 몇 년 동안 팀에서 인원에 비해 많은 과제를 수행하다 보니 1인 1과제로 흘러간 기간이 길었다. 그 결과 팀에서 이슈 관리, 코드 관리 규칙이 자연스럽게 사라졌고, 각자 편한 방식으로 일하는 “사일로”가 생겼다.

문제는 다시 협업이 필요해졌을 때였다.

규칙을 새로 도입하려면 설계하는 데 시간이 들고
규칙을 지키는 과정이 오히려 생산성을 깎는 느낌이 들었다
게다가 옆자리에서 바로 물어보는 습관이 생겨서, 그때그때 구두로 문제를 해결해버리곤 했다

근데 이 방식은 오래 가지 못했다. 실시간 소통이 계속되면 집중 시간이 줄어들고, 말로만 전달하면 기록이 남지 않아 기억에 의존하다가 증발해버리고 말았다.

그래서 결론적으로, 우리 팀 상황에 맞는 Git 협업 전략을 진짜로 만들기로 했다.

Git 협업 성숙도 4단계

나는 Git을 사용하는 과정을 다음 4단계로 본다.

1단계: Git이 무섭다

commit, push는 하지만, 브랜치를 만들고 merge하다가 충돌 나는 상황이 두렵다. 다만, 요즘은 AI 도구 덕분에 충돌 해결 자체는 쉬워졌고, 그래서 기능을 외우기보다는 개념을 이해하는 쪽이 더 중요해졌다.

2단계: 코드는 합쳐지는데 히스토리는 망한다

사람마다 브랜치 만들고, PR 올리고, merge하는 기준이 달라서 충돌은 안 나는데 히스토리가 전혀 관리되지 않는 상태가 된다.

3단계: 규칙은 있는데 너무 무겁다

규칙대로 굴러가긴 하는데 지키느라 오버헤드가 크다. 특히 PR에서 시간을 많이 뺏기면 규칙이 생산성을 떨어뜨린다는 인식이 강해진다.

4단계: 규칙이 익숙해져서 생산성이 오른다

규칙이 자연스러워지고, PR을 통해 서로의 코드 이해도가 올라가면서 결과적으로 개발 속도, 품질, 리뷰 속도가 같이 개선된다.

이 글에서는 2단계에 머물던 팀이 4단계로 올라가게 만든 방식을 정리하려고 한다.

거버넌스: 완벽한 정답은 없고 팀에 맞는 답이 있다

처음에 제일 고민했던 건 거버넌스를 어떻게 세울까였고, 그 결론은 완벽한 거버넌스는 없고, 팀에 맞는 거버넌스만 있다는 것이다. 팀의 업무 흐름(티켓 단위, 배포 주기, 리뷰 문화)이나 인력 구성(신규 인원 비중, 협업 빈도)이 다르면 같은 전략도 결과가 완전히 달라진다. 그래서 좋아 보이는 방식이 아니라, 지금 팀이 겪는 병목을 줄이는 방향으로 후보를 비교했다.

대표적으로 이런 선택지들이 있다.

메인라인 개발(Mainline development)
기능별 브랜치(Branch-per-feature)
상태 브랜치(State branching)
예정된 배포(Scheduled deployment)

우리 팀은 기능별 브랜치 + 상태 브랜치를 선택했다. 기능 단위로 티켓을 쪼개서 히스토리를 깔끔하게 만들고, 상태 브랜치로 배포,안정화 흐름을 분리하는 게 현재 팀 상황에 제일 잘 맞았다. 중요한 건 유행하는 전략을 그대로 사용하는 것보다, 팀 상황을 기준으로 선택하는 거였다.

규칙을 문서화하는 방식: Cookbook으로 만들기

우리는 Jira와 Bitbucket을 쓰고 있었고, 이 화면에서 이렇게 하면 된다를 그대로 따라할 수 있는 cookbook 형식 가이드를 작성해서 공유했다.

형식을 이렇게 잡은 이유는 원칙만 적으면 해석이 사람마다 달라지고, 결국 또 각자 방식으로 흩어지기 때문이다. 반대로 화면 단위로 “어디를 눌러서 무엇을 해야 하는지”가 정리되어 있으면, 신규 인원도 시행착오 없이 그대로 따라할 수 있었다. 그래서 가이드는 브랜치 생성 → PR 생성 → 리뷰 요청 → merge까지를 한 흐름으로 묶고, 예외 케이스(급한 hotfix, 롤백, 충돌 처리)도 최소한으로 포함했다.

가이드를 운영하면서 “수정이 필요한 부분”은 팀원이 직접 보완해주게 만들어서 문서를 지침이 아니라 하나의 살아있는 팀 규칙으로 만들었다. 문서가 팀의 합의로 계속 업데이트되니까, 규칙이 누가 시켜서 하는 것이 아니라 우리 방식으로 굳어지기 시작했다.

핵심 규칙: 변경이 둘 이상이면 티켓도 브랜치도 분리

우리 팀이 가장 중요하게 둔 규칙은 이거였다.

변경사항 2개 이상 시 Jira 티켓 분리
티켓 분리 시 브랜치 분리
(버그 픽스 제외) 규칙 준수 원칙
main 브랜치 직접 push 금지
PR approve 이후 merge 허용(Bitbucket 권한/정책으로 제한)

이 규칙 하나가 히스토리 관리 실패와 리뷰가 안 달리는 문제를 동시에 줄였다. 리뷰어 입장에선 변경 범위가 작아지니까 리뷰가 쉬워지고, 작성자 입장에선 흐름이 깔끔해졌다.

운영 루틴: 주간회의 → 티켓 → 브랜치 → commit → PR → 리뷰 → merge

우리는 다음 루틴을 팀의 기본 리듬으로 잡았다.

주 1회 주간회의: 주간 이슈 정리 및 담당 배정
개인 티켓 생성(회의 내용 기반)
티켓 기반 브랜치 생성
작업 commit 및 PR 요청
approve 후 merge
반복

이 구조의 장점은, 이슈 관리 시스템만 봐도 누가 뭘 하고 있는지가 보인다는 것이다. 그래서 다음 주간회의 전까지 상황에 따라 티켓을 유동적으로 재분배할 수도 있었다.

주의한 점: 티켓에 너무 힘주지 않기

티켓 자체를 완벽하게 쓰려다 보면 시간이 오래 걸릴 수 있다. 대신 우리는 이쪽에 힘을 줬다.

commit 메시지에 맥락을 남기기
PR 요청 설명에 의사결정의 이유를 남기기

그래야 PR이 빨라지고, 기록이 남아서, 말로만 소통하다 증발하는 문제도 줄었다.

피어리뷰 운영: 고쳐주기보다 성장시키기

피어리뷰는 보통 3종류로 나뉜다.

안 돌아가는 코드(버그/치명적 문제)
모범사례 미준수(컨벤션, 중복 구현 등)
리뷰어의 개인 선호(취향, 스타일)

이때 리뷰 방식은 크게 두 가지가 있다.

리뷰어가 직접 수정 commit을 한다
리뷰 코멘트로 방향을 준다

우리는 가능한 빨리 리뷰를 달아주는 방식을 택했고, 직접 수정 commit은 되도록 지양했다.

우리의 목표는 “빨리 합치기”가 아니라 “리뷰를 통해 성장하기”였기 때문이다. 리뷰어가 잘못된 점과 수정 방향을 남기면, 커미터가 자신의 결정 이유와 비교하면서 스스로 납득 가능한 해답을 다시 만들었다.

초반에는 리뷰 시간이 오래 걸렸지만, 코드베이스 이해가 올라가고 서로의 개발 스타일/철학을 알게 되면서 결과적으로 개발 속도, 품질, 리뷰 속도가 같이 올라갔다.

AI 시대에도 Git 협업 문화는 더 중요해진다

AI 때문에 사람이 코드를 직접 작성할 이유는 점점 줄어들 수 있다. 그런데 아이러니하게도, AI가 만든 코드일수록 오너십은 더 강하게 필요하다.

PR에 “부끄럽지 않은 코드”를 올리려고 사람이 한 번 더 검수해야 하고
팀은 PR 리뷰로 2차 검수를 하면서
AI로 인한 무분별한 코드 생성과 기술부채 누적을 막아야 한다

그래서 나는 오히려 앞으로는

Jira 같은 티켓 시스템으로 태스크를 더 작게 쪼개고
작은 단위로 commit/PR을 만들고
AI로 빠르게 구현하되 사람이 책임지고 검수하는 흐름

이런 방식이 생산성을 더 끌어올릴 거라고 생각한다. 그리고 그 바탕에 Git 협업 문화가 있다.

마무리

이 글은 “나 혼자 편하게”가 아니라, 팀이 함께 좋은 문화를 만들고 공유하면서 생산성을 올리는 과정에 대한 기록이다.

완벽한 규칙은 없지만, 우리 팀에 맞는 규칙을 만들고 계속 조정하면서 2단계에서 4단계로 올라가는 건 충분히 가능했다. 결국 핵심은 거창한 방법론이 아니라, 작게 시작해서 팀이 실제로 지킬 수 있는 형태로 굳히는 것이었다.