Gateway API Extensions

• 1: BackendTrafficPolicy
• 2: ClientTrafficPolicy
• 3: SecurityPolicy

1 - BackendTrafficPolicy

Before you Begin

• Gateway API Extensions

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 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.

Targets

BackendTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms:

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)

# 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

# Gateway-level policy (lower precedence) - 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

---
# Route-level policy (higher precedence)
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: route-policy
spec:
  targetRefs:
    - kind: HTTPRoute
      name: my-route
  circuitBreaker:
    maxConnections: 50

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

# 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.

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 section below).

Policy Merging

BackendTrafficPolicy supports merging configurations using the mergeType field, which allows route-level policies to combine with gateway-level policies rather than completely overriding them. This enables layered policy strategies where platform teams can set baseline configurations at the Gateway level, while application teams can add specific policies for their routes.

Merge Types

• StrategicMerge: Uses Kubernetes strategic merge patch semantics, providing intelligent merging for complex data structures including arrays
• JSONMerge: Uses RFC 7396 JSON Merge Patch semantics, with simple replacement strategy where arrays are completely replaced

Example Usage

Here’s an example demonstrating policy merging for rate limiting:

# Platform team: Gateway-level policy with global abuse prevention
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: global-backendtrafficpolicy
spec:
  rateLimit:
    type: Global
    global:
      rules:
      - clientSelectors:
        - sourceCIDR:
            type: Distinct
            value: 0.0.0.0/0
        limit:
          requests: 100
          unit: Second
        shared: true
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: eg

---
# Application team: Route-level policy with specific limits
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: route-backendtrafficpolicy
spec:
  mergeType: StrategicMerge  # Enables merging with gateway policy
  rateLimit:
    type: Global
    global:
      rules:
      - clientSelectors:
        - sourceCIDR:
            type: Distinct
            value: 0.0.0.0/0
        limit:
          requests: 5
          unit: Minute
        shared: false
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: signup-service-httproute

In this example, the route-level policy merges with the gateway-level policy, resulting in both rate limits being enforced: the global 100 requests/second abuse limit and the route-specific 5 requests/minute limit.

Key Constraints

• The mergeType field can only be set on policies targeting child resources (like HTTPRoute), not parent resources (like Gateway)
• When mergeType is unset, no merging occurs - only the most specific policy takes effect
• The merged configuration combines both policies, enabling layered protection strategies

Related Resources

• Circuit Breakers
• Failover
• Fault Injection
• Global Rate Limit
• Local Rate Limit
• Load Balancing
• Response Compression
• Response Override
• BackendTrafficPolicy API Reference

2 - ClientTrafficPolicy

Before you Begin

• Gateway API Extensions

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.

Targets

ClientTrafficPolicy can be attached to Gateway API resources using two targeting mechanisms:

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)

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

# 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:

# 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
• HTTP Request Headers
• HTTP/3
• Mutual TLS: External Clients to the Gateway
• ClientTrafficPolicy API Reference

3 - SecurityPolicy

Before you Begin

• Gateway API Extensions

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 only properly authenticated and authorized requests are allowed through your backend services.

SecurityPolicy is designed for you to enforce access controls through configuration at the edge of your infrastructure in a declarative, Kubernetes-native way, without needing to configure complex proxy rules manually.

Use Cases

1. Authentication Methods:

   • Authenticate client apps using mTLS, JWTs, API keys, or Basic Auth
   • Authenticate users with OIDC Provider integration

2. Authorization Controls:

   • Define and enforce authorization rules based on user roles and permissions
   • Integrate with external authorization services for real-time policy decisions
   • JWT Token Authorization Checks

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.

Targets

SecurityPolicy can be attached to Gateway API resources using two targeting mechanisms:

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)

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

# 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.

# 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:

# 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 affects only the HTTPS listener, while policy B applies to the rest of the listeners in the gateway. Since Policy A is more specific, the system will show Overridden=True for Policy B on the https listener.

Related Resources

• API Key Authentication
• Basic Authentication
• CORS
• External Authorization
• IP Allowlist/Denylist
• JWT Authentication
• JWT Claim Based Authorization
• OIDC Authorization
• SecurityPolicy API Reference