This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Gateway API Extensions

Before You Begin

Overview

Gateway API Extensions let you configure extra features that aren’t part of the standard Kubernetes Gateway API. These extensions are built by the teams that create and maintain Gateway API implementations. The Gateway API was designed to be extensible safe, and reliable. In the old Ingress API, people had to use custom annotations to add new features, but those weren’t type-safe, making it hard to check if their configuration was correct. With Gateway API Extensions, implementers provide type-safe Custom Resource Definitions (CRDs). This means every configuration you write has a clear structure and strict rules, making it easier to catch mistakes early and be confident your setup is valid.

Use Cases

Here are some examples of what kind of features extensions include:

  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 introduces a set of Gateway API extensions that enable users to leverage the power of the Envoy proxy. 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, translating them into xDS configurations 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.

1 - BackendTrafficPolicy

Before you Begin

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.

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:

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

2 - ClientTrafficPolicy

Before you Begin

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:

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

3 - SecurityPolicy

Before you Begin

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

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