Concepts

Learn about key concepts when working with Envoy Gateway

Overview

Envoy Gateway is a Kubernetes-native API Gateway and reverse proxy control plane. It simplifies deploying and operating Envoy Proxy as a data plane by using the standard Gateway API and its own extensible APIs.

By combining Envoy’s performance and flexibility with Kubernetes-native configuration, Envoy Gateway helps platform teams expose and manage secure, observable, and scalable APIs with minimal operational overhead.

Why Use Envoy Gateway?

Traditionally, configuring Envoy Proxy required deep networking expertise and writing complex configuration files. Envoy Gateway removes that barrier by:

  • Integrating tightly with Kubernetes through the Gateway API
  • Providing custom CRDs for advanced traffic policies
  • Automatically translating Kubernetes resources into Envoy config
  • Managing the lifecycle of Envoy Proxy instances

Envoy Gateway is designed to be simple for app developers, powerful for platform engineers, and production-ready for large-scale deployments.

Structure

The different layers of Envoy Gateway are the following:

LayerDescription
User ConfigurationUsers define routing, security, and traffic policies using standard Kubernetes Gateway API resources, optionally extended with Envoy Gateway CRDs.
Envoy Gateway ControllerA control plane component that watches Gateway API and Envoy Gateway-specific resources, translates them, and produces configuration for Envoy Proxy.
Envoy Proxy(Data Plane)A high-performance proxy that receives and handles live traffic according to the configuration generated by Envoy Gateway.

Together, these layers create a system that’s:

  • Easy to configure
  • Powerful enough for complex needs
  • Standardized and familiar
  • Ready for the future

Resources

There are several resources that play a part in enabling you to meet your Kubernetes ingress traffic handling needs. This page provides a brief overview of the resources you’ll be working with.

Kubernetes Gateway API Resources

  • GatewayClass: Defines a class of Gateways with common configuration.
  • Gateway: Specifies how traffic can enter the cluster.
  • Routes: HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute: Define routing rules for different types of traffic.

Envoy Gateway (EG) API Resources

  • EnvoyProxy: Represents the deployment and configuration of the Envoy proxy within a Kubernetes cluster, managing its lifecycle and settings.
  • EnvoyPatchPolicy, ClientTrafficPolicy, SecurityPolicy, BackendTrafficPolicy, EnvoyExtensionPolicy, BackendTLSPolicy: Additional policies and configurations specific to Envoy Gateway.
  • Backend: A resource that makes routing to cluster-external backends easier and makes access to external processes via Unix Domain Sockets possible.
ResourceAPIRequiredPurposeReferencesDescription
GatewayClassGateway APIYesGateway ConfigCoreDefines a class of Gateways with common configuration.
GatewayGateway APIYesGateway ConfigGatewayClassSpecifies how traffic can enter the cluster.
HTTPRoute GRPCRoute TLSRoute TCPRoute UDPRouteGateway APIYesRoutingGatewayDefine routing rules for different types of traffic. Note:For simplicity these resources are referenced collectively as Route in the References column
BackendEG APINoRoutingN/AUsed for routing to cluster-external backends using FQDN or IP. Can also be used when you want to extend Envoy with external processes accessed via Unix Domain Sockets.
ClientTrafficPolicyEG APINoTraffic HandlingGatewaySpecifies policies for handling client traffic, including rate limiting, retries, and other client-specific configurations.
BackendTrafficPolicyEG APINoTraffic HandlingGateway, RouteSpecifies policies for traffic directed towards backend services, including load balancing, health checks, and failover strategies. Note:Most specific configuration wins
SecurityPolicyEG APINoSecurityGateway, RouteDefines security-related policies such as authentication, authorization, and encryption settings for traffic handled by Envoy Gateway. Note:Most specific configuration wins
BackendTLSPolicyGateway APINoSecurityServiceDefines TLS settings for backend connections, including certificate management, TLS version settings, and other security configurations. This policy is applied to Kubernetes Services.
EnvoyProxyEG APINoCustomize & ExtendGatewayClass, GatewayThe EnvoyProxy resource represents the deployment and configuration of the Envoy proxy itself within a Kubernetes cluster, managing its lifecycle and settings. Note:Most specific configuration wins
EnvoyPatchPolicyEG APINoCustomize & ExtendGatewayClass, GatewayThis policy defines custom patches to be applied to Envoy Gateway resources, allowing users to tailor the configuration to their specific needs. Note:Most specific configuration wins
EnvoyExtensionPolicyEG APINoCustomize & ExtendGateway, Route, BackendAllows for the configuration of Envoy proxy extensions, enabling custom behavior and functionality. Note:Most specific configuration wins
HTTPRouteFilterEG APINoCustomize & ExtendHTTPRouteAllows for the additional request/response processing.

Next Steps

For a deeper understanding of Envoy Gateway’s building blocks, you may also wish to explore these conceptual guides: