옮겨 온 문서는 템플릿 안의 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).
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을 오래됨 상한까지 내준다.
할 일.
- snapshot의 나이를 본다.
SERVE_LAST_KNOWN_GOOD는 정상적인 degraded 상태다. STALE_BEYOND_BOUND는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이 없으면 내린 backend가 트래픽을 끝없이 받는다.- 뜨는 인스턴스의
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는 통과했지만 아무것도 증명하지 않았다.