docs: Conceptual documentation for CTP, BTP, SecurityPolicy & Gateway API Extensions#5946
docs: Conceptual documentation for CTP, BTP, SecurityPolicy & Gateway API Extensions#5946melsal13 wants to merge 10 commits intoenvoyproxy:mainfrom
Conversation
Signed-off-by: melsal13 <mmvsal13@gmail.com>
update branch
Signed-off-by: melsal13 <mmvsal13@gmail.com>
Signed-off-by: melsal13 <mmvsal13@gmail.com>
Signed-off-by: melsal13 <mmvsal13@gmail.com>
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #5946 +/- ##
==========================================
+ Coverage 65.82% 65.86% +0.03%
==========================================
Files 217 217
Lines 36016 36020 +4
==========================================
+ Hits 23709 23726 +17
+ Misses 10832 10818 -14
- Partials 1475 1476 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Signed-off-by: melsal13 <mmvsal13@gmail.com>
Signed-off-by: melsal13 <mmvsal13@gmail.com>
melsal13
changed the title
update branch with changes from upstream
|
|
||
| Lastly, it's important to note that even when you apply a policy to a Gateway, the policy's effects are tracked separately for each backend service referenced in your routes. For example, if you set up circuit breaking on a Gateway with multiple backend services, each backend service will have its own independent circuit breaker counter. This ensures that issues with one backend service don't affect the others. | ||
|
|
||
| ## Best Practices |
There was a problem hiding this comment.
imo best practices without being prescriptive is not very helpful
There was a problem hiding this comment.
lets add it once each step can be computed using a cmd
There was a problem hiding this comment.
That makes sense! Considering removing Best Practices section from concept template completely.
There was a problem hiding this comment.
great, can we track that with a GH issue
|
|
||
| `BackendTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages traffic to your backend services. | ||
|
|
||
| `BackendTrafficPolicy` uses the `targetRefs` field to specify which Gateway API resources the policy should apply to. You can target: |
There was a problem hiding this comment.
or targetSelectors to specify using labels
| - A Gateway: to apply the policy to all routes in that gateway | ||
| - A specific Route (HTTPRoute or GRPCRoute): to apply the policy to that route's traffic | ||
|
|
||
| When multiple policies target the same resource, the most specific configuration wins. |
There was a problem hiding this comment.
example explaining this would be very helpful
There was a problem hiding this comment.
Added examples to CTP, BTP and SP
|
|
||
| ## Overview | ||
|
|
||
| `ClientTrafficPolicy` is an extension to the Kubernetes Gateway API that controls how Envoy Gateway handles incoming traffic from clients. It can configure connection behavior, security settings, and protocol optimizations at the gateway level. |
There was a problem hiding this comment.
lets rm security settings from here
There was a problem hiding this comment.
instead of protocol optimizations, can we say protocol specific configuration
There was a problem hiding this comment.
my bad things, there's a section on tls in there, can we explicitly say TLS settings instead
|
|
||
| `ClientTrafficPolicy` is an extension to the Kubernetes Gateway API that controls how Envoy Gateway handles incoming traffic from clients. It can configure connection behavior, security settings, and protocol optimizations at the gateway level. | ||
|
|
||
| It can act as a gatekeeper that manages how external clients connect to your services, helping you maintain security, performance, and stability. |
There was a problem hiding this comment.
this isnt right, its similar to a traffic controller analogy that you used for BTP, but b/w external clients and the gateway
There was a problem hiding this comment.
https://gateway.envoyproxy.io/docs/tasks/traffic/client-traffic-policy/#introduction has some language for this
There was a problem hiding this comment.
Updated and referenced the doc you provided!
| `ClientTrafficPolicy` is particularly useful in scenarios where you need to: | ||
|
|
||
| - **Strengthen security:** Implement IP allow/deny lists and authenticate clients with mutual TLS | ||
| - **Optimize performance:** Enable HTTP/3 and fine-tune connection settings |
There was a problem hiding this comment.
this entire section doesnt look right
There was a problem hiding this comment.
I copied the API content into chatgpt, here's what I got, which we got further tweak
1. Enforcing Secure Client Connections
When TLS termination is required at the edge, tls settings enable enforcement of secure protocols, mutual TLS (mTLS), and certificate validation policies to protect internal workloads.
2. Managing Long-Lived Connections
For applications that rely on persistent connections (e.g., IoT or streaming APIs), the tcpKeepalive field enables fine-tuned control of TCP keepalive behavior, helping to detect broken client connections and optimize resource usage.
4. Reliable Client IP Detection
With the clientIPDetection field, platform admins can configure trusted proxy chains to correctly resolve the client IP, improving audit logs and geo-based access control.
5. Path Normalization and Routing Safety
The path settings allow normalization or sanitization of incoming request paths, reducing ambiguity and ensuring compatibility with backend routing rules.
7. Fine-Tuned Connection Timeouts
The timeout field is useful for customizing idle timeouts, read timeouts, and handshake durations based on application latency characteristics.
8. Controlling HTTP Protocol Behavior
The http1, http2, and http3 sections enable protocol-specific tuning, essential for compatibility and performance tuning across clients.
9. Active Listener Health Checks
The healthCheck field provides configuration for proactive health signaling of listeners, allowing integration with load balancers and automated failover mechanisms.
There was a problem hiding this comment.
Updated your suggestion to :
-
Enforce TLS Security
Configure TLS termination, mutual TLS (mTLS), and certificate validation at the edge. -
Manage Client Connections
Control TCP keepalive behavior and connection timeouts for optimal resource usage. -
Handle Client Identity
Configure trusted proxy chains to correctly resolve client IPs for logging and access control. -
Normalize Request Paths
Sanitize incoming request paths to ensure compatibility with backend routing rules. -
Tune HTTP Protocols
Configure HTTP/1, HTTP/2, and HTTP/3 settings for compatibility and performance. -
Monitor Listener Health
Set up health checks for integration with load balancers and failover mechanisms.
|
|
||
| This separation ensures that different types of traffic can be managed independently while still maintaining overall control over gateway resources. | ||
|
|
||
| ## Best Practices |
There was a problem hiding this comment.
re thinking, it may be best to create a new top level section called Best Practices so we can include specific things like #5851 in there
|
|
||
| You can apply a `ClientTrafficPolicy` to a Gateway resource, and it will affect how that gateway handles client connections. The policy's effects are applied at the listener level, with some important distinctions: | ||
|
|
||
| - For HTTP listeners: All HTTP listeners in a Gateway share a common connection counter |
There was a problem hiding this comment.
this doesnt seem very useful
|
|
||
| `ClientTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages incoming client traffic. | ||
|
|
||
| You can apply a `ClientTrafficPolicy` to a Gateway resource, and it will affect how that gateway handles client connections. The policy's effects are applied at the listener level, with some important distinctions: |
There was a problem hiding this comment.
similar to BTP, can we add a note around how things are targeted, targetRefs and targetSelectors and what can be targeted - Gateway or Listener ( by sectionName). and that Listner policy / most specific policy wins
| Envoy Gateway uses a policy attachment model, where custom policies are applied to standard Gateway API resources (like HTTPRoute or Gateway) without modifying the core API. This approach provides separation of concerns and makes it easier to manage configurations across teams. | ||
|
|
||
| These extensions are processed through Envoy Gateway’s control plane, which translates them into xDS configurations that are applied to Envoy Proxy instances. This layered architecture allows for consistent, scalable, and production-grade traffic control without needing to manage raw Envoy configuration directly. | ||
|
|
There was a problem hiding this comment.
can we explicitly name each extension with a 1 liner and add a hyperlink so they link out to concepts and API reference ?
lets add
- EnvoyExtensionPolicy
- EnvoyProxy
- HTTPRouteFIlter
- Backend
here, and we can add a Concepts page for it later
There was a problem hiding this comment.
Added a one liner as a note. All link to their respective api refs.
As I create more conceptual docs, I'll link them in the related resources section
There was a problem hiding this comment.
I missed mentioning EnvoyPatchPolicy 🙈
|
|
||
| ## Overview | ||
|
|
||
| Gateway Extensions are mechanisms that allow implementation-specific features to be added to the Kubernetes Gateway API without modifying its core specification. They enable Gateway API implementations like Envoy Gateway to expose their unique capabilities while maintaining compatibility with the standard API. Extensions follow defined patterns that preserve the role-oriented design of Gateway API while allowing for customization to address specific use cases not covered by the core API. |
There was a problem hiding this comment.
should we have a dedicated page for Gateway API Extensions or add it under https://gateway.envoyproxy.io/docs/concepts/concepts_overview/#envoy-gateway-eg-api-resources
cc @missBerg ?
updating branch with changes from main
Signed-off-by: melsal13 <mmvsal13@gmail.com>
|
Closing this pr and replacing with the following: |
2 participants
What type of PR is this?
Conceptual documentation explaining ClientTrafficPolicy, BackendTrafficPolicy, SecurityPolicy and Gateway API Extensions.
What this PR does / why we need it:
Helps onboard new users.
Which issue(s) this PR fixes:
Fixes #2070
Fixes #5949
Fixes #2072
Fixes #5948
Release Notes: No