docs: add GRPC Timeouts task (BackendTrafficPolicy) - #9631
Conversation
GRPCRoute has no native timeouts field yet (tracked upstream at kubernetes-sigs/gateway-api#3139), and users repeatedly rediscover the BackendTrafficPolicy workaround by word of mouth. Document how to configure gRPC timeouts via BackendTrafficPolicy: requestTimeout for unary RPCs, and requestTimeout: 0s + maxStreamDuration/streamIdleTimeout for streaming RPCs. Signed-off-by: Andrey Maltsev <maltsev.andrey@gmail.com>
✅ Deploy Preview for cerulean-figolla-1f9435 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b48b662050
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| targetRefs: | ||
| - group: gateway.networking.k8s.io | ||
| kind: GRPCRoute | ||
| name: yages |
There was a problem hiding this comment.
When readers follow this task top-to-bottom, the unary example has already created a BackendTrafficPolicy targeting GRPCRoute/yages, and this streaming example creates a second policy for that same route. Envoy Gateway processes BackendTrafficPolicies in creation order and resolveBackendTrafficPolicyRouteTargetRef rejects a later policy that targets an already-attached route as Conflicted, so grpc-stream-timeout will not be accepted and the streaming timeout settings won't take effect unless the reader deletes/reuses the first policy or uses a separate route.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Good catch — fixed in 2c85563. Both examples now reuse a single BackendTrafficPolicy named grpc-timeouts, and I added a note in Prerequisites that a GRPCRoute accepts only one BackendTrafficPolicy (a second is rejected as Conflicted), so the two examples are alternatives and re-applying updates the same policy rather than creating a conflicting second one.
…-timeouts examples A GRPCRoute accepts only one BackendTrafficPolicy; a second policy targeting the same route is rejected as Conflicted (backendtrafficpolicy.go resolveBackendTrafficPolicyRouteTargetRef). The unary and streaming examples now reuse a single policy name (grpc-timeouts) and a note explains they are alternatives, so following the task top-to-bottom no longer produces a Conflicted second policy. Signed-off-by: Andrey Maltsev <maltsev.andrey@gmail.com>
|
Can you include an example and a way to "prove" the timeouts work as expected? |
- Correct the HTTPRoute/GRPCRoute links to the /reference/api-types/ path used by the other traffic docs (the /api-types/ form 404s, failing docs-lint link check). - Address review: add a Verification step that proves the timeout is programmed into the Envoy route config via egctl (route timeout / maxStreamDuration), plus an end-to-end grpcurl DEADLINE_EXCEEDED example and a note that the sample yages backend does not delay. Signed-off-by: Andrey Maltsev <maltsev.andrey@gmail.com>
|
Thanks @jukie — added in 21943e4. The Verification section now:
I called out that the sample Also fixed the docs-lint failure (the HTTPRoute/GRPCRoute links now use the |
3 participants
What this PR does
Adds a GRPC Timeouts task doc (
site/content/en/latest/tasks/traffic/grpc-timeouts.md) showing how to configure timeouts for gRPC traffic with aBackendTrafficPolicy.Why
The Gateway API
GRPCRouteresource has no nativetimeoutsfield yet — it's tracked upstream at kubernetes-sigs/gateway-api#3139 (triage/accepted,priority/important-longterm), andGRPCRouteRulein the current CRD still lacks it. In the meantime Envoy Gateway already supports gRPC timeouts viaBackendTrafficPolicy(closing #6511 for unary and #5446 / #6508 for streaming), but this isn't documented, so users keep rediscovering it by word of mouth (e.g. the workaround reshared in kubernetes-sigs/gateway-api#3139). This doc closes that gap.Contents
timeout.http.requestTimeoutbounds the request.requestTimeout: "0s"disables the per-request timeout so long-lived streams aren't cut off, thenmaxStreamDuration/streamIdleTimeoutbound them (with"0s"= indefinite).Docs-only; no code change. Follows the existing
http-timeouts.mdstructure and the establishedBackendTrafficPolicyAPI-reference link convention. markdownlint-clean (no trailing whitespace, consistent heading levels).