feat(operator): document Service annotations added in 2.2.0#5544
Open
sandromodarelli wants to merge 5 commits into
Open
feat(operator): document Service annotations added in 2.2.0#5544sandromodarelli wants to merge 5 commits into
sandromodarelli wants to merge 5 commits into
Conversation
Documents the 11 konghq.com/* Service annotations added in operator 2.2.0, under the Gateway Deployment > Advanced Usage section.
Three practical guides showing how to use the Service annotations added in operator 2.2.0: - Set timeouts and retries (connect/read/write-timeout, retries) - Set the Host header sent upstream (host-header) - Configure load balancing with KongUpstreamPolicy (upstream-policy)
✅ Deploy Preview for kongdeveloper ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
lmilan
reviewed
Jun 12, 2026
| } | ||
| } | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
Suggested change
| {:.no-copy-code} | |
| } | ||
| } | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
Suggested change
| {:.no-copy-code} | |
| Running on Pod echo-6d8f4c9b7-xk2vt. | ||
| Running on Pod echo-6d8f4c9b7-xk2vt. | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
Suggested change
| {:.no-copy-code} | |
Comment on lines
+62
to
+67
| | Annotation | Value | Effect | | ||
| |---|---|---| | ||
| | `konghq.com/connect-timeout` | `3000` | {{site.base_gateway}} waits up to 3 seconds to establish a TCP connection | | ||
| | `konghq.com/read-timeout` | `5000` | {{site.base_gateway}} waits up to 5 seconds for the upstream to send a response | | ||
| | `konghq.com/write-timeout` | `5000` | {{site.base_gateway}} waits up to 5 seconds when sending data upstream | | ||
| | `konghq.com/retries` | `3` | Failed requests are retried up to 3 times before returning an error | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Annotation | Value | Effect | | |
| |---|---|---| | |
| | `konghq.com/connect-timeout` | `3000` | {{site.base_gateway}} waits up to 3 seconds to establish a TCP connection | | |
| | `konghq.com/read-timeout` | `5000` | {{site.base_gateway}} waits up to 5 seconds for the upstream to send a response | | |
| | `konghq.com/write-timeout` | `5000` | {{site.base_gateway}} waits up to 5 seconds when sending data upstream | | |
| | `konghq.com/retries` | `3` | Failed requests are retried up to 3 times before returning an error | | |
| {% table %} | |
| columns: | |
| - title: "Annotation" | |
| key: "annotation" | |
| - title: "Value" | |
| key: "value" | |
| - title: "Effect" | |
| key: "effect" | |
| rows: | |
| - annotation: "`konghq.com/connect-timeout`" | |
| value: "`3000`" | |
| effect: "{{site.base_gateway}} waits up to 3 seconds to establish a TCP connection" | |
| - annotation: "`konghq.com/read-timeout`" | |
| value: "`5000`" | |
| effect: "{{site.base_gateway}} waits up to 5 seconds for the upstream to send a response" | |
| - annotation: "`konghq.com/write-timeout`" | |
| value: "`5000`" | |
| effect: "{{site.base_gateway}} waits up to 5 seconds when sending data upstream" | |
| - annotation: "`konghq.com/retries`" | |
| value: "`3`" | |
| effect: "Failed requests are retried up to 3 times before returning an error" | |
| {% endtable %} |
| url: /operator/dataplanes/reference/service-annotations/ | ||
| --- | ||
|
|
||
| By default, {{site.base_gateway}} sets the `Host` header to the IP address of the individual Pod it is forwarding the request to. Some upstream services perform host-based virtual hosting or access control and require a specific `Host` header value. You can override this behavior using the `konghq.com/host-header` annotation. |
Contributor
There was a problem hiding this comment.
Suggested change
| By default, {{site.base_gateway}} sets the `Host` header to the IP address of the individual Pod it is forwarding the request to. Some upstream services perform host-based virtual hosting or access control and require a specific `Host` header value. You can override this behavior using the `konghq.com/host-header` annotation. | |
| By default, {{site.base_gateway}} sets the `Host` header to the IP address of the individual Pod it forwards the request to. Some upstream services perform host-based virtual hosting or access control and require a specific `Host` header value. You can override this behavior using the `konghq.com/host-header` annotation. |
| done | ||
| ``` | ||
|
|
||
| Requests for `user-bob` consistently hit a different Pod than requests for `user-alice`. |
Contributor
There was a problem hiding this comment.
I tried it a few times but I still get the same Pod with both headers values.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documents the 11
konghq.com/*Service annotations added in Kong Operator 2.2.0 (changelog:Hybridgateway: add support for...). No equivalent existed in operator docs.New pages:
app/operator/dataplanes/reference/service-annotations.md— reference listing all 11 annotations under Gateway Deployment > Advanced Usageapp/_how-tos/operator/operator-dataplane-service-timeouts-retries.md— set connect/read/write timeouts and retries on a Serviceapp/_how-tos/operator/operator-dataplane-service-host-header.md— override the Host header sent upstreamapp/_how-tos/operator/operator-dataplane-service-upstream-policy.md— consistent-hashing load balancing viaKongUpstreamPolicyapp/_includes/prereqs/operator/httpbin-service-route.md— shared prereq include (httpbin + HTTPRoute) reused by two how-tosPreview Links
Checklist
descriptionentry in frontmatter.