Files
grpc-library/docs/runbooks/grpc-advanced-capabilities.md
T
DongHyeonka ce83f4d550
pr / ci (pull_request) Successful in 1m9s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 optional build를 전제로 했다(`-p
platforms/optional-build`, 템플릿 registry·workflow 경로, "벤더드 플랫폼").
하네스 뼈대의 루트 지침과 문제 정의는 비어 있었다.

- 루트 AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것(core-api 순수성, Stable이
  advanced를 안 씀, 템플릿에 기대지 않음, 배포한 버전 불변, 버전 규칙),
  지도, 맡은 일, 검증 진입점. 비대화형 세션의 플러그인 설치 두 줄.
- README: 무엇인가, 받는 법(exclusiveContent), 지원 표, 구조, 문서 지도,
  서명, 이력(filter-repo, 커밋 SHA·리뷰 ID는 템플릿 기준).
- docs/work/README.md·gates.md·release.md: 고치는 법, 단계와 바꾼 것별
  게이트, 템플릿과 같이 고치기(composite), 릴리스와 소유자가 할 일
  (PACKAGES_TOKEN, SIGNING_KEY·SIGNING_PASSWORD, 첫 태그 v1.0.0).
- CHANGELOG.md(1.0.0 미발행, 옮기는 법), docs/README.md(지도, 머리 블록).
- scripts/verify.sh: unit·pr·main·release 단계. 라이브러리라 app은 없다.
- 살아 있는 문서(grpc·grpc-advanced AGENTS.md, 지원 매트릭스, runbook):
  경로·패키지·optional build 문장을 이 repo 기준으로. ADR·설계서 본문은
  기록이라 고치지 않았다.
- docs/vision.md는 소유자가 쓰는 문서라 비워 두었다.

검증: scripts/verify.sh docs rc=0(AGENTS.md 38줄, 장부 JSON).
2026-11-08 11:22:12 +09:00

4.9 KiB

Runbook: gRPC advanced capabilities

범위: :grpc-advanced:* family. 여기 있는 것은 모두 기본으로 꺼져 있고, 배포가 이름을 대기 전까지 꺼진 채로 있다. 지금 이 family의 어떤 것도 런타임 조립에 들어가지 않는다.

스위치는 app.grpc.advanced.<capability>.enabled다. capability 이름 목록과 기본 등급은 GrpcAdvancedCapability(defaultGrade())가 가진다. 근거가 있는 배포는 GrpcAdvancedFeatureFlags.withGrade로 등급을 바꾼다.


capability가 뜨기를 거부한다

GrpcAdvancedModuleGuard는 세 가지로 거부하고, 고치는 법이 다르다.

메시지에 있는 말 뜻 고치는 법
"its feature flag is not set" 아무도 켜지 않았다 메시지가 이름 댄 속성을 설정한다
"tracked rather than implemented" 등급이 WATCH다 여기서 할 일은 없다. 그 capability는 구현되지 않았다
"uncharacterised failure modes" 등급이 EXPERIMENTAL이고 여기는 운영이다 운영 승인을 기록하거나, 운영 밖에서 돌린다

거부 메시지는 늘 속성 키를 이름 댄다. 그래서 첫 경우는 지원 문의가 아니라 설정 한 줄이다.


xDS: control plane이 사라졌다

보이는 것. control plane에 닿지 않는데 클라이언트는 아직 라우팅한다.

뜻. GrpcXdsFailurePolicy가 마지막으로 정상이던 snapshot을 오래됨 상한까지 내준다.

할 일.

  1. snapshot의 나이를 본다. SERVE_LAST_KNOWN_GOOD는 정상적인 degraded 상태다.
  2. STALE_BEYOND_BOUND는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이 없으면 내린 backend가 트래픽을 끝없이 받는다.
  3. 뜨는 인스턴스의 NO_SNAPSHOT_YET은 control plane에 한 번도 닿지 못했다는 뜻이다. 라우팅 없이 뜨지 않고, 첫 fetch 시간 상한이 지나면 실패한다.

xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 더하지 않는다. GrpcXdsProfile이 APPLICATION 재시도 소유자를 거부한다. 두 곳에 정의한 재시도는 결정이 아니라 해석 순서가 이기는 쪽을 정하기 때문이다.


gRPC-Web: 브라우저 호출이 멈췄다가 상태 없이 실패한다

거의 언제나 proxy다. gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다. proxy의 CORS expose_headers에 grpc-status와 grpc-message가 있는지 확인한다. GrpcWebProxyContract.violations가 정확히 이것을 보고하고, 참조 설정 grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml에 그것이 들어 있다.

메서드가 client streaming이나 bidirectional streaming이면 gRPC-Web으로는 아예 되지 않는다. 브라우저는 메시지 stream을 보낼 방법이 없다. GrpcWebRpcSupport.require가 그런 메서드를 거부한다.


Servlet: 전송 설정이 무시되는 것 같다

무시된다. 소켓은 컨테이너가 가지므로 keepalive 조정, 최대 연결 수명, flow-control window 조정은 컨테이너의 몫이다. 이 저장소에는 그것을 거부할 Servlet 전송 코드가 없으니 컨테이너에서 설정한다.

Servlet 실행은 Netty 인증을 대신하지 않는다.


Hedging: backend 부하가 두 배가 됐다

상한 안이면 예상한 일이다. hedging은 중복 부하를 내고 꼬리 지연을 줄인다. GrpcHedgingResult는 duplicateBackendCalls와 cancelledLoserAttempts를 둘 다 기록한다. 지연 개선만 보여 주는 대시보드는 그 교환을 공짜처럼 보이게 한다.

확인할 것. GrpcHedgingBudget은 hedge를 끝난 호출의 비율로 제한한다. 중복 부하가 그 비율을 넘으면 예산이 쓰이지 않고 있다는 뜻이다. coordinator 밖에서 무언가가 hedge를 보내고 있다.

읽기 전용 unary 메서드가 아니면 hedging을 거부한다. hedge된 변경은 설계상 두 번 돈다. 멱등 키도 소용없다. 두 번째 시도는 실패를 다시 시도하는 것이 아니라 진행 중인 성공을 중복한다.


capability 승격

ADVANCED_STABLE로 올리려면 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험, 7일 soak이 필요하다. Stable 기본값은 30일이 필요하다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은 바뀌지 않는다. 이것은 리뷰 점검 목록이다. 이것을 코드로 다시 적은 GrpcAdvancedPromotionGate는 자기 테스트 말고는 부르는 곳이 없어 지웠다(리뷰 2026-09-24 S5-lead-4).

어떤 suite를 증거로 들기 전에, 그 suite가 필요한 실제 인프라(proxy, 컨테이너, control plane, toolchain)에 대고 돌았는지 확인한다. 인프라 없이 돈 suite는 통과했지만 아무것도 증명하지 않았다.