pr / ci (pull_request) Successful in 1m9s
옮겨 온 문서는 템플릿 안의 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).
89 lines
4.9 KiB
Markdown
89 lines
4.9 KiB
Markdown
# 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는 통과했지만 아무것도 증명하지 않았다.
|