문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이 영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로 정했다(design-docs `repo-structure/README.md` 3.2절). 방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약· 현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위 줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드· 명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한 영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을 괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본 지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은 `scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에 남긴다. 위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤 문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다. 검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움, head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조, check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
5.1 KiB
결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-31
- 요약: Stable discovery는 DNS와 정적 목록이고 Kubernetes에서는 누가 부하를 나누는지 profile이 정한다는 결정이다.
- 현재 정본:
docs/compatibility/grpc-support-matrix.md
ADR-GRPC-006: Stable discovery는 DNS와 static이고, Kubernetes profile은 누가 분산하는지 이름으로 댄다
- 상태: 채택
- 날짜: 2026-08-31
- 범위:
:grpc:grpc-runtime(예전grpc-discovery,grpc-client)
배경
gRPC channel의 discovery 설정에는 런타임 증상이 없는 실패 방식이 있다: 동작은 하는데, 대시보드가 말하는 일을 하지 않는다.
구체적인 경우는 Kubernetes Service ClusterIP 위의 round_robin이다. Service는 가상 주소 하나라서 resolver가 endpoint 하나를
돌려주고 client 쪽 분산기는 돌려 가며 보낼 대상이 없다. kube-proxy는 연결할 때 pod를 고르고, HTTP/2 연결은 오래 살기
때문에, 그 client의 모든 요청이 연결이 사는 동안 같은 pod로 간다. 실패하는 것은 없다. 설정은 round_robin이라고 말하고,
metric은 요청이 pod가 아니라 client 사이에 퍼진 것을 보여 주며, 「client 쪽 부하 분산을 한다」는 결론은 아무도 확인할
계기가 없는 방식으로 틀렸다.
거울상 실수는 headless record 위의 pick_first다. 많은 pod 중 하나에 client를 묶는다.
따로, service mesh는 재시도를 누가 가지는지 바꾸고, mesh 라우팅을 더하면서 자기 재시도 정책을 빼지 않은 배포는 효과가 곱해지는 재시도자 둘을 가진다.
결정
Stable resolver는 Static, DNS, Unix domain socket이고, Stable 부하 분산은 pick_first와 round_robin이다.
GrpcDiscoveryPolicyValidator.requireStableScheme은 xds, consul, etcd, eureka를 이름으로 거절하고, 그것이 모르는
scheme이 아니라 자기 control plane과 승격 gate를 가진 Advanced capability라고 메시지로 말한다.
짝 맞춤은 의도가 아니라 해석된 주소 수와 대조한다. GrpcResolverProfile은 expectedAddressCount를 싣고,
GrpcStableLoadBalancer.effective가 그 수의 endpoint 위에서 정책이 무언가를 분산하는지 답한다. 주소 하나 위의
round_robin profile은 보고되는 위반이고, 그 메시지는 그것이 일어나지 않는 퍼뜨리기를 설명한다고 말한다.
Kubernetes 배포는 자기 라우팅 모드를 이름으로 대고, 그 모드가 분산기와 재시도 소유자를 둘 다 정한다.
GrpcKubernetesRoutingMode에는 값이 셋 있다 — K8S_VIP, K8S_HEADLESS, MESH — 그리고 GrpcKubernetesProfile은 재시도
소유자가 프로세스 안에서 재시도하는 mesh profile을 거절한다.
오래 사는 stream을 싣는 profile은 재연결 예산과 readiness 비우기 유예를 밝혀야 한다. stream은 사는 내내 client를 pod
하나에 묶으므로, 모든 rollout, eviction, scale-down이 그것을 끝낸다. GrpcKubernetesProfileValidator는 긴 stream을 싣는
VIP profile과, 재연결 예산보다 짧은 비우기 유예도 알린다 — 후자는 client가 다른 곳으로 재연결을 마치기 전에 pod가 응답을
멈춘다는 뜻이다.
DNS profile은 새로 고쳐야 한다. GrpcResolverProfile은 DNS에서 새로 고침 간격 0을 거절한다. 기동 때 한 번 해석한
channel은 한 시간 전에 없어진 주소로 계속 보내고, 그 결과인 UNAVAILABLE은 rollout이 끝난 지 한참 뒤에도 건강하지 않은
배포처럼 보인다.
결과
validator는 하나가 아니라 둘이다. GrpcDiscoveryPolicyValidator는 분산기가 자기가 볼 주소 위에서 무언가를 하는지
묻는다. GrpcKubernetesProfileValidator는 배포 모양, 재시도 소유자, stream 의무가 맞는지 묻는다. 배포는 resolver profile이
앞뒤가 맞으면서도 재시도를 두 곳에 둘 수 있다. 그래서 둘을 합치면 한 답이 다른 답을 가린다.
expectedAddressCount는 어딘가에서 와야 한다. 선언한 숫자이고, 선언은 틀릴 수 있다. 그래도 아무것도 비교하지 않는
대안보다 낫다: 틀린 선언은 누가 적어 둔 틀린 말이고, 빠진 선언은 아무도 묻지 않은 질문이다.
GrpcChannelProfileValidator는 기동 때 알 수 있는 곳에서는 해석된 수를 받고, 알 수 없는 곳에서는 짐작해서 아직 해석할 수
없는 이름에서 실패하는 대신 검사를 건너뛴다.
xDS에는 닿을 수 있지만, 이 길로는 아니다. xDS는 grpc-advanced(패키지 resilience/xds)에서 자기 capability flag와
운영 승인 뒤에 있고, GrpcXdsStartupGuard.advertisableAsStableSupport()가 false를 돌려주므로 Stable 지원 설명이 조용히
넓어질 수 없다. ADR-GRPC-ADV-001을 본다.