diff --git a/site/content/en/latest/concepts/gateway_api_extensions/backend-traffic-policy.md b/site/content/en/latest/concepts/gateway_api_extensions/backend-traffic-policy.md index 1cc981a1bb..06c99d39e3 100644 --- a/site/content/en/latest/concepts/gateway_api_extensions/backend-traffic-policy.md +++ b/site/content/en/latest/concepts/gateway_api_extensions/backend-traffic-policy.md @@ -29,17 +29,58 @@ Think of it as a traffic controller between your gateway and backend services. I `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: +### Targets -1. Using `targetRefs` to directly reference specific Gateway resources -2. Using `targetSelectors` to match Gateway resources based on labels +BackendTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms: -The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins. +1. **Direct Reference (`targetRefs`)**: Explicitly reference specific resources by name and kind. +2. **Label Selection (`targetSelectors`)**: Match resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors)) -For example, consider these two policies: +```yaml +# Direct reference targeting +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: direct-policy +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + circuitBreaker: + maxConnections: 50 + +--- +# Label-based targeting +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: selector-policy +spec: + targetSelectors: + - kind: HTTPRoute + matchLabels: + app: payment-service + rateLimit: + type: Local + local: + requests: 10 + unit: Second +``` + +The policy applies to all resources that match either targeting method. You can target various Gateway API resource types including +`Gateway`, `HTTPRoute`, `GRPCRoute`, `TCPRoute`, `UDPRoute`, `TLSRoute`. + +**Important**: A BackendTrafficPolicy can only target resources in the same namespace as the policy itself. + +### Precedence + +When multiple BackendTrafficPolicies apply to the same resource, Envoy Gateway resolves conflicts using a precedence hierarchy based on the target resource type, regardless of how the policy was attached: + +1. **Route-level policies** (HTTPRoute, GRPCRoute, etc.) - Highest precedence +2. **Gateway-level policies** - Lower precedence ```yaml -# Policy 1: Applies to all routes in the gateway +# Gateway-level policy (lower precedence) - Applies to all routes in the gateway apiVersion: gateway.envoyproxy.io/v1alpha1 kind: BackendTrafficPolicy metadata: @@ -52,7 +93,7 @@ spec: maxConnections: 100 --- -# Policy 2: Applies to a specific route +# Route-level policy (higher precedence) apiVersion: gateway.envoyproxy.io/v1alpha1 kind: BackendTrafficPolicy metadata: @@ -65,9 +106,47 @@ spec: 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. +In this example, the HTTPRoute `my-route` would use `maxConnections: 50` from the route-level policy, overriding the gateway-level setting of 100. + +#### Multiple Policies at the Same Level + +When multiple BackendTrafficPolicies target the same resource at the same hierarchy level (e.g., multiple policies targeting the same HTTPRoute), Envoy Gateway uses the following tie-breaking rules: + +1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence +2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence + +```yaml +# Policy created first - takes precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: alpha-policy + creationTimestamp: "2023-01-01T10:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + circuitBreaker: + maxConnections: 30 + +--- +# Policy created later - lower precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: beta-policy + creationTimestamp: "2023-01-01T11:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + circuitBreaker: + maxConnections: 40 +``` + +In this example, `alpha-policy` would take precedence due to its earlier creation time, so the HTTPRoute would use `maxConnections: 30`. -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. +When the `mergeType` field is unset, no merging occurs and only the most specific configuration takes effect. However, policies can be configured to merge with parent policies using the `mergeType` field (see [Policy Merging](#policy-merging) section below). ## Policy Merging diff --git a/site/content/en/latest/concepts/gateway_api_extensions/client-traffic-policy.md b/site/content/en/latest/concepts/gateway_api_extensions/client-traffic-policy.md index 8dc47a3063..b5afbfb06d 100644 --- a/site/content/en/latest/concepts/gateway_api_extensions/client-traffic-policy.md +++ b/site/content/en/latest/concepts/gateway_api_extensions/client-traffic-policy.md @@ -36,14 +36,67 @@ Think of `ClientTrafficPolicy` as a set of rules for your Gateway's entry points `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: +### Targets -1. Using `targetRefs` to directly reference specific Gateway resources -2. Using `targetSelectors` to match Gateway resources based on labels +ClientTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms: -The policy applies to all Gateway resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins. +1. **Direct Reference (`targetRefs`)**: Explicitly reference specific Gateway resources by name and kind. +2. **Label Selection (`targetSelectors`)**: Match Gateway resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors)) -For example, consider these policies targeting the same Gateway Listener: +The policy applies to all Gateway resources that match either targeting method. + +**Important**: A ClientTrafficPolicy can only target Gateway resources in the same namespace as the policy itself. + +### Precedence + +When multiple ClientTrafficPolicies apply to the same resource, Envoy Gateway resolves conflicts using section-level specificity and creation-time priority: + +1. **Section-specific policies** (targeting specific listeners via `sectionName`) - Highest precedence +2. **Gateway-wide policies** (targeting entire Gateway) - Lower precedence + +#### Multiple Policies at the Same Level + +When multiple ClientTrafficPolicies target the same resource at the same specificity level (e.g., multiple policies targeting the same Gateway listener section), Envoy Gateway uses the following tie-breaking rules: + +1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence +2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence + +```yaml +# Policy created first - takes precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: ClientTrafficPolicy +metadata: + name: alpha-policy + creationTimestamp: "2023-01-01T10:00:00Z" +spec: + targetRefs: + - kind: Gateway + name: my-gateway + sectionName: https-listener + timeout: + http: + idleTimeout: 30s + +--- +# Policy created later - lower precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: ClientTrafficPolicy +metadata: + name: beta-policy + creationTimestamp: "2023-01-01T11:00:00Z" +spec: + targetRefs: + - kind: Gateway + name: my-gateway + sectionName: https-listener + timeout: + http: + idleTimeout: 40s +``` + +In this example, `alpha-policy` would take precedence due to its earlier creation time, so the listener would use `idleTimeout: 30s`. + +For example, consider these policies with different specificity levels targeting the same Gateway: ```yaml # Policy A: Targets a specific listener in the gateway diff --git a/site/content/en/latest/concepts/gateway_api_extensions/security-policy.md b/site/content/en/latest/concepts/gateway_api_extensions/security-policy.md index 12f0eccfdd..4eac2fb50e 100644 --- a/site/content/en/latest/concepts/gateway_api_extensions/security-policy.md +++ b/site/content/en/latest/concepts/gateway_api_extensions/security-policy.md @@ -27,14 +27,146 @@ title: "SecurityPolicy" ## 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: +`SecurityPolicy` is implemented as a Kubernetes Custom Resource Definition (CRD) and follows the policy attachment model. -1. Using `targetRefs` to directly reference specific Gateway resources -2. Using `targetSelectors` to match Gateway resources based on labels +### Targets -The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins. +SecurityPolicy can be attached to Gateway API resources using two targeting mechanisms: -For example, consider these policies targeting the same Gateway Listener: +1. **Direct Reference (`targetRefs`)**: Explicitly reference specific resources by name and kind. +2. **Label Selection (`targetSelectors`)**: Match resources based on their labels (see [targetSelectors API reference](../../api/extension_types#targetselectors)) + +The policy applies to all resources that match either targeting method. You can target various Gateway API resource types including `Gateway`, `HTTPRoute`, and `GRPCRoute`. + +**Important**: A SecurityPolicy can only target resources in the same namespace as the policy itself. + +### Precedence + +When multiple SecurityPolicies apply to the same resource, Envoy Gateway resolves conflicts using a precedence hierarchy based on the target resource type and section-level specificity: + +1. **Route rule-level policies** (HTTPRoute/GRPCRoute with `sectionName` targeting specific rules) - Highest precedence +2. **Route-level policies** (HTTPRoute, GRPCRoute without `sectionName`) - High precedence +3. **Listener-level policies** (Gateway with `sectionName` targeting specific listeners) - Medium precedence +4. **Gateway-level policies** (Gateway without `sectionName`) - Lowest precedence + +#### Multiple Policies at the Same Level + +When multiple SecurityPolicies target the same resource at the same hierarchy level (e.g., multiple policies targeting the same HTTPRoute), Envoy Gateway uses the following tie-breaking rules: + +1. **Creation Time Priority**: The oldest policy (earliest `creationTimestamp`) takes precedence +2. **Name-based Sorting**: If policies have identical creation timestamps, they are sorted alphabetically by namespaced name, with the first policy taking precedence + +```yaml +# Policy created first - takes precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: alpha-policy + creationTimestamp: "2023-01-01T10:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + cors: + allowOrigins: + - exact: https://example.com + +--- +# Policy created later - lower precedence +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: beta-policy + creationTimestamp: "2023-01-01T11:00:00Z" +spec: + targetRefs: + - kind: HTTPRoute + name: my-route + cors: + allowOrigins: + - exact: https://different.com +``` + +In this example, `alpha-policy` would take precedence due to its earlier creation time, so the HTTPRoute would use the CORS setting from `alpha-policy`. + +```yaml +# HTTPRoute with named rules +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: my-route +spec: + rules: + - name: rule-1 # Named rule for sectionName targeting + matches: + - path: + value: "/api" + backendRefs: + - name: api-service + port: 80 + +--- +# Route rule-level policy (highest precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: rule-policy +spec: + targetRef: + kind: HTTPRoute + name: my-route + sectionName: rule-1 # Targets specific named rule + cors: + allowOrigins: + - exact: https://rule.example.com + +--- +# Route-level policy (high precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: route-policy +spec: + targetRef: + kind: HTTPRoute + name: my-route # No sectionName = entire route + cors: + allowOrigins: + - exact: https://route.example.com + +--- +# Listener-level policy (medium precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: listener-policy +spec: + targetRef: + kind: Gateway + name: my-gateway + sectionName: https-listener # Targets specific listener + cors: + allowOrigins: + - exact: https://listener.example.com + +--- +# Gateway-level policy (lowest precedence) +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: gateway-policy +spec: + targetRef: + kind: Gateway + name: my-gateway # No sectionName = entire gateway + cors: + allowOrigins: + - exact: https://gateway.example.com +``` + +In this example, the specific rule `rule-1` within HTTPRoute `my-route` would use the CORS settings from the route rule-level policy (`https://rule.example.com`), overriding the route-level, listener-level, and gateway-level settings. + +For section-specific targeting, consider these policies with different hierarchy levels targeting the same Gateway: ```yaml # Policy A: Applies to a specific listener