docs: Conceptual documentation for CTP, BTP, SecurityPolicy & Gateway API Extensions

site/content/en/latest/concepts/backend-traffic-policy.md

@@ -0,0 +1,80 @@
+---
+title: "BackendTrafficPolicy"
+---
+## Before you Begin
+- [Gateway API Extensions](gateway-api-extensions.md)
+
+## Overview
+`BackendTrafficPolicy` is an extension to the Kubernetes Gateway API that controls how Envoy Gateway communicates with your backend services. It can configure connection behavior, resilience mechanisms, and performance optimizations without requiring changes to your applications.
+
+Think of it as a traffic controller that sits between your gateway and backend services. It can detect problems, prevent failures from spreading, and optimize request handling to improve system stability.
+
+## Use Cases
+
+`BackendTrafficPolicy` is particularly useful in scenarios where you need to:
+
+1. **Protect your services:** 
+   Limit connections and reject excess traffic when necessary
+
+2. **Build resilient systems:** 
+   Detect failing services and redirect traffic
+
+3. **Improve performance:** 
+   Optimize how requests are distributed and responses are handled
+
+4. **Test system behavior:** 
+   Inject faults and validate your recovery mechanisms
+
+## BackendTrafficPolicy in Envoy Gateway
+
+`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. You can attach it to Gateway API resources in two ways:
+
+1. Using `targetRefs` to directly reference specific Gateway resources
+2. Using `targetSelectors` to match Gateway resources based on labels
+
+The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+
+For example, consider these two policies:
+
+```yaml
+# Policy 1: Applies to all routes in the gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: gateway-policy
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+  circuitBreaker:
+    maxConnections: 100
+
+---
+# Policy 2: Applies to a specific route
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: route-policy
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  circuitBreaker:
+    maxConnections: 50
+```
+
+In this example `my-route` and `my-gateway` would both affect the route. However, since Policy 2 targets the route directly while Policy 1 targets the gateway, Policy 2's configuration (`maxConnections: 50`) will take precedence for that specific route.
+
+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.
+
+## Related Resources
+
+- [Circuit Breakers](../tasks/traffic/circuit-breaker)
+- [Failover](../tasks/traffic/failover)
+- [Fault Injection](../tasks/traffic/fault-injection)
+- [Global Rate Limit](../tasks/traffic/global-rate-limit)
+- [Local Rate Limit](../tasks/traffic/local-rate-limit)
+- [Load Balancing](../tasks/traffic/load-balancing)
+- [Response Compression](../tasks/traffic/response-compression)
+- [Response Override](../tasks/traffic/response-override)
+- [BackendTrafficPolicy API Reference](../api/extension_types#backendtrafficpolicy)

site/content/en/latest/concepts/client-traffic-policy.md

@@ -0,0 +1,86 @@
+---
+title: "ClientTrafficPolicy"
+---
+## Before you Begin
+- [Gateway API Extensions](gateway-api-extensions.md)
+
+## Overview
+
+`ClientTrafficPolicy` is an extension to the Kubernetes Gateway API that allows system administrators to configure how the Envoy Proxy server behaves with downstream clients. It is a policy attachment resource that can be applied to Gateway resources and holds settings for configuring the behavior of the connection between the downstream client and Envoy Proxy listener.
+
+Think of `ClientTrafficPolicy` as a set of rules for your Gateway's entry points - it lets you configure specific behaviors for each listener in your Gateway, with more specific rules taking precedence over general ones.
+
+## Use Cases
+
+`ClientTrafficPolicy` is particularly useful in scenarios where you need to:
+
+1. **Enforce TLS Security**
+   Configure TLS termination, mutual TLS (mTLS), and certificate validation at the edge.
+
+2. **Manage Client Connections**
+   Control TCP keepalive behavior and connection timeouts for optimal resource usage.
+
+3. **Handle Client Identity**
+   Configure trusted proxy chains to correctly resolve client IPs for logging and access control.
+
+4. **Normalize Request Paths**
+   Sanitize incoming request paths to ensure compatibility with backend routing rules.
+
+5. **Tune HTTP Protocols**
+   Configure HTTP/1, HTTP/2, and HTTP/3 settings for compatibility and performance.
+
+6. **Monitor Listener Health**
+   Set up health checks for integration with load balancers and failover mechanisms.
+
+## ClientTrafficPolicy in Envoy Gateway
+
+`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 attach it to Gateway API resources in two ways:
+
+1. Using `targetRefs` to directly reference specific Gateway resources
+2. Using `targetSelectors` to match Gateway resources based on labels
+
+The policy applies to all Gateway resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+
+For example, consider these policies targeting the same Gateway Listener:
+
+```yaml
+# Policy A: Targets a specific listener in the gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: ClientTrafficPolicy
+metadata:
+  name: listener-specific-policy
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+      sectionName: https-listener  # Targets specific listener
+  timeout:
+    http:
+      idleTimeout: 30s
+
+---
+# Policy B: Targets the entire gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: ClientTrafficPolicy
+metadata:
+  name: gateway-wide-policy
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway  # Targets all listeners
+  timeout:
+    http:
+      idleTimeout: 60s
+```
+
+In this case:
+- Policy A will be applied/attached to the specific Listener defined in the `targetRef.SectionName`
+- Policy B will be applied to the remaining Listeners within the Gateway. Policy B will have an additional status condition Overridden=True.
+
+## Related Resources
+
+- [Connection Limit](../tasks/traffic/connection-limit)
+- [HTTP Request Headers](../tasks/traffic/http-request-headers)
+- [HTTP/3](../tasks/traffic/http3)
+- [Mutual TLS: External Clients to the Gateway](../tasks/security/mutual-tls.md)
+- [ClientTrafficPolicy API Reference](../api/extension_types#clienttrafficpolicy)

site/content/en/latest/concepts/gateway-api-extensions.md

@@ -0,0 +1,39 @@
+---
+title: "Gateway API Extensions"
+---
+## Before you Begin
+- [The Gateway API](https://gateway-api.sigs.k8s.io/)
+
+## 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.
+
+## Use Cases
+
+1. **Advanced Traffic Management:** 
+    Implementing sophisticated load balancing algorithms, circuit breaking, or retries not defined in the core API
+2. **Enhanced Security Controls:** 
+    Adding implementation-specific TLS configurations, authentication mechanisms, or access control rules
+3. **Observability Integration:** 
+    Connecting Gateway resources to monitoring systems, logging pipelines, or tracing frameworks
+4. **Custom Protocol Support:** 
+    Extending beyond HTTP/TCP/UDP with specialized protocol handling
+5. **Rate Limiting and Compression:** 
+    Implementing traffic policing specific to the implementation's capabilities
+
+## Gateway API Extensions in Envoy Gateway
+
+The Envoy Gateway API is a set of Gateway API extensions that enable advanced traffic management capabilities in Envoy Gateway. These extensions build on top of the Kubernetes Gateway API by introducing custom resources that expose powerful features of Envoy Proxy in a Kubernetes-native way.
+
+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.
+
+{{% alert title="Current Extensions" color="info" %}}
+Currently supported extensions include [`ClientTrafficPolicy`](../api/extension_types#clienttrafficpolicy), [`BackendTrafficPolicy`](../api/extension_types#backendtrafficpolicy), [`SecurityPolicy`](../api/extension_types#securitypolicy), [`EnvoyExtensionPolicy`](../api/extension_types#envoyextensionpolicy), [`EnvoyProxy`](../api/extension_types#envoyproxy), [`HTTPRouteFilter`](../api/extension_types#httproutefilter), and [`Backend`](../api/extension_types#backend).
+{{% /alert %}}
+
+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.
+
+## Related Resources
+- [ClientTrafficPolicy](client-traffic-policy.md)
+- [BackendTrafficPolicy](backend-traffic-policy.md)
+- [SecurityPolicy](security-policy.md)

site/content/en/latest/concepts/security-policy.md

@@ -0,0 +1,79 @@
+---
+title: "SecurityPolicy"
+---
+
+## Before you Begin
+- [Gateway API Extensions](gateway-api-extensions.md)
+
+## Overview
+
+`SecurityPolicy` is an Envoy Gateway extension to the Kubernetes Gateway API that allows you to define authentication and authorization requirements for traffic entering your gateway. It acts as a security layer that ensures only properly authenticated and authorized requests are allowed through to your backend services.
+
+`SecurityPolicy` is designed for users who want to enforce access controls at the edge of their infrastructure in a declarative, Kubernetes-native way—without needing to manually configure complex proxy rules.
+
+## Use Cases
+
+1. **Authentication Methods:**
+    - Authenticate clients using JWT, OIDC, API keys, or Basic Auth
+
+2. **Authorization Controls:**
+    - Define and enforce authorization rules based on user roles and permissions
+    - Integrate with external authorization services for real-time policy decisions
+
+3. **Cross-Origin Security:**
+    - Configure CORS to allow or restrict cross-origin requests for APIs
+
+## SecurityPolicy in Envoy Gateway
+
+`SecurityPolicy` is implemented as a Kubernetes Custom Resource Definition (CRD) and follows the policy attachment model. You can attach it to Gateway API resources in two ways:
+
+1. Using `targetRefs` to directly reference specific Gateway resources
+2. Using `targetSelectors` to match Gateway resources based on labels
+
+The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+
+For example, consider these policies targeting the same Gateway Listener:
+
+```yaml
+# Policy A: Applies to a specific listener
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: listener-policy
+  namespace: default
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+      sectionName: https  # Applies only to "https" listener
+  cors:
+    allowOrigins:
+      - exact: https://example.com
+---
+# Policy B: Applies to the entire gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: SecurityPolicy
+metadata:
+  name: gateway-policy
+  namespace: default
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway  # Applies to all listeners
+  cors:
+    allowOrigins:
+      - exact: https://default.com
+```
+
+In the example, policy A takes effect only on the https listener while policy B applies to the rest of the listeners in the gateway. The system will show Overridden=True for Policy B on the https listener, since Policy A is more specific.
+
+## Related Resources
+- [API Key Authentication](../tasks/security/apikey-auth.md)
+- [Basic Authentication](../tasks/security/basic-auth.md)
+- [CORS](../tasks/security/cors.md)
+- [External Authorization](../tasks/security/ext-auth.md)
+- [IP Allowlist/Denylist](../tasks/security/restrict-ip-access.md)
+- [JWT Authentication](../tasks/security/jwt-authentication.md)
+- [JWT Claim Based Authorization](../tasks/security/jwt-claim-authorization.md)
+- [OIDC Authorization](../tasks/security/oidc.md)
+- [SecurityPolicy API Reference](../api/extension_types#securitypolicy)

site/content/en/v1.3/concepts/backend-traffic-policy.md

@@ -0,0 +1,80 @@
+---
+title: "BackendTrafficPolicy"
+---
+## Before you Begin
+- [Gateway API Extensions](gateway-api-extensions.md)
+
+## Overview
+`BackendTrafficPolicy` is an extension to the Kubernetes Gateway API that controls how Envoy Gateway communicates with your backend services. It can configure connection behavior, resilience mechanisms, and performance optimizations without requiring changes to your applications.
+
+Think of it as a traffic controller that sits between your gateway and backend services. It can detect problems, prevent failures from spreading, and optimize request handling to improve system stability.
+
+## Use Cases
+
+`BackendTrafficPolicy` is particularly useful in scenarios where you need to:
+
+1. **Protect your services:** 
+   Limit connections and reject excess traffic when necessary
+
+2. **Build resilient systems:** 
+   Detect failing services and redirect traffic
+
+3. **Improve performance:** 
+   Optimize how requests are distributed and responses are handled
+
+4. **Test system behavior:** 
+   Inject faults and validate your recovery mechanisms
+
+## BackendTrafficPolicy in Envoy Gateway
+
+`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. You can attach it to Gateway API resources in two ways:
+
+1. Using `targetRefs` to directly reference specific Gateway resources
+2. Using `targetSelectors` to match Gateway resources based on labels
+
+The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+
+For example, consider these two policies:
+
+```yaml
+# Policy 1: Applies to all routes in the gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: gateway-policy
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+  circuitBreaker:
+    maxConnections: 100
+
+---
+# Policy 2: Applies to a specific route
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: route-policy
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  circuitBreaker:
+    maxConnections: 50
+```
+
+In this example `my-route` and `my-gateway` would both affect the route. However, since Policy 2 targets the route directly while Policy 1 targets the gateway, Policy 2's configuration (`maxConnections: 50`) will take precedence for that specific route.
+
+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.
+
+## Related Resources
+
+- [Circuit Breakers](../tasks/traffic/circuit-breaker)
+- [Failover](../tasks/traffic/failover)
+- [Fault Injection](../tasks/traffic/fault-injection)
+- [Global Rate Limit](../tasks/traffic/global-rate-limit)
+- [Local Rate Limit](../tasks/traffic/local-rate-limit)
+- [Load Balancing](../tasks/traffic/load-balancing)
+- [Response Compression](../tasks/traffic/response-compression)
+- [Response Override](../tasks/traffic/response-override)
+- [BackendTrafficPolicy API Reference](../api/extension_types#backendtrafficpolicy)