In the previous article, we explored how Kubernetes Gateway API uses GatewayClass, Gateway, and HTTPRoute to manage traffic routing.
But there is another interesting question:
How does an HTTPRoute become an actual routing configuration inside Envoy Proxy?
Kubernetes doesn't directly configure Envoy Proxy whenever you create an HTTPRoute.
Instead, Envoy Gateway watches Gateway API resources, translates them into its internal representation, generates Envoy configuration, and delivers that configuration through xDS.
Let's follow that process step by step.
1. Understanding the Control Plane and Data Plane
Before looking at the translation process, let's understand two important components.
Control Plane – Envoy Gateway
The control plane watches Kubernetes resources and determines how traffic should be configured.
It handles:
- Watching Gateway API resources.
- Validating and processing configuration.
- Translating resources into an internal representation.
- Generating Envoy Proxy configuration.
- Delivering configuration through xDS.
Data Plane – Envoy Proxy
The data plane handles actual application traffic.
It is responsible for:
- Receiving incoming requests.
- Matching requests against configured routes.
- Selecting the appropriate backend.
- Forwarding traffic to backend endpoints.
- Returning responses to clients.
This control-plane/data-plane separation describes Envoy Gateway's implementation architecture. It is not a requirement that Gateway API imposes on every implementation.
2. What Happens When You Create a Gateway?
When you create a Gateway resource, Envoy Gateway processes it and provisions or configures the Envoy Proxy infrastructure associated with that Gateway.
The process generally involves:
- Envoy Gateway observes the Gateway resource.
- It checks the referenced GatewayClass and listener configuration.
- It provisions an Envoy Proxy workload.
- It creates a Service exposing the proxy, which is type
LoadBalancerby default. - It configures the proxy to handle traffic according to the Gateway configuration.
The external address depends on the Kubernetes environment and whether a LoadBalancer implementation is available.
Important: The Service exposing Envoy Proxy is different from the backend application Service referenced by an HTTPRoute.
The proxy Service exposes the entry point for incoming traffic. The backend Service identifies the application that should receive matching requests.
3. How Does Envoy Gateway Process an HTTPRoute?
Let's use a simple example.
Assume Envoy Gateway is installed and a GatewayClass using its controller already exists.
For reference, its controller name is:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
Now create a Gateway:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: default
spec:
gatewayClassName: example-gateway-class
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: Same
Next, create an HTTPRoute:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: shop-route
namespace: default
spec:
parentRefs:
- name: example-gateway
hostnames:
- shop.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: shop-service
port: 80
What happens after applying these resources?
Step 1: Resource observation
Envoy Gateway watches the Gateway API resources through the Kubernetes API.
Step 2: Validation and reference resolution
The controller checks whether the HTTPRoute can attach to the Gateway and whether its backend references are valid.
For example:
- Does the referenced Gateway exist?
- Does the listener allow this route to attach?
- Does the backend Service exist?
- Is the referenced Service port valid?
The controller reports the outcome through resource status conditions.
Step 3: Translation
Envoy Gateway translates the processed Gateway API resources into an internal representation.
Step 4: Configuration generation and delivery
The internal representation is converted into Envoy configuration resources and delivered to Envoy Proxy through xDS.
This is how a Kubernetes HTTPRoute becomes an actual routing configuration.
4. Inside the Translation Process: Gateway API to IR
One of the most interesting parts of Envoy Gateway is its Intermediate Representation (IR).
Instead of directly converting every Kubernetes resource into Envoy-specific configuration, Envoy Gateway first translates Gateway API resources into an internal model.
The translation flow looks like this:
Gateway API Resources
|
v
Envoy Gateway
Translator
|
v
Intermediate Representation
(IR)
|
v
xDS Translator
|
v
Envoy Configuration
|
v
Envoy Proxy
Why is this important?
Gateway API describes what traffic routing should look like. Envoy Proxy needs its own configuration format to implement that routing.
The IR acts as an intermediate layer between these two models.
It helps Envoy Gateway organize routing, listeners, clusters, endpoints, and other configuration before generating the final Envoy resources.
Exploring translation with egctl
Envoy Gateway provides egctl, a command-line tool for inspecting and translating configuration.
For releases that support these experimental commands, you can use:
Translate Gateway API resources into IR:
egctl x translate --from gateway-api --to ir -f gateway-resources.yaml
Translate Gateway API resources into xDS:
egctl x translate --from gateway-api --to xds -f gateway-resources.yaml
The first command helps inspect Envoy Gateway's intermediate representation.
The second command helps inspect the Envoy configuration resources generated from the input.
These are experimental translation commands, so their availability and flags can vary between releases. Check the documentation for your installed version before using them.
The input file should contain the relevant Gateway API resources and any referenced resources required for translation. Incomplete input can produce incomplete configuration.
What does the generated Envoy configuration look like?
The following is a simplified illustration of an Envoy route configuration, not literal output from egctl:
name: http_route
virtual_hosts:
- name: shop_example_com
domains:
- shop.example.com
routes:
- match:
prefix: /
route:
cluster: shop_service
Let's understand the important fields:
-
virtual_hosts: Defines the hostnames Envoy should match. -
domains: Contains the hostname, such asshop.example.com. -
routes: Contains the routing rules. -
match: Defines which incoming requests match the rule. -
cluster: Identifies the upstream cluster that handles matching requests.
This illustrates how the original HTTPRoute intent is represented in Envoy's routing configuration.
The actual generated configuration can contain additional fields and may differ depending on the Envoy Gateway version and enabled features.
5. How Does xDS Configure Envoy Proxy?
After Envoy Gateway generates the required configuration, it delivers that configuration to Envoy Proxy through xDS.
xDS is the configuration discovery protocol used by Envoy.
Some important xDS resource types include:
| xDS resource | Purpose |
|---|---|
| LDS | Listener Discovery Service |
| RDS | Route Discovery Service |
| CDS | Cluster Discovery Service |
| EDS | Endpoint Discovery Service |
| SDS | Secret Discovery Service |
Let's understand them with our example.
- LDS: Defines the listener that accepts incoming HTTP traffic.
- RDS: Defines how requests are matched against hostnames and paths.
- CDS: Defines the upstream clusters representing backend destinations.
- EDS: Supplies endpoint information to clusters when endpoint discovery is used.
- SDS: Provides TLS certificates and other security-related secrets when required.
For example, when a request arrives for shop.example.com, Envoy uses its listener and route configuration to identify the appropriate backend cluster.
It then uses the cluster's configured endpoint information to forward the request.
This is how Envoy Proxy receives the configuration needed to process real application traffic.
6. How Does Envoy Gateway Discover Backend Pods?
Now let's look at another important part: backend endpoint discovery.
Consider this HTTPRoute reference:
backendRefs:
- name: shop-service
port: 80
The HTTPRoute references a Kubernetes Service, but Envoy Gateway also needs to know which actual Pods are available behind that Service.
Kubernetes maintains this information through EndpointSlices.
The process looks like this:
HTTPRoute
|
v
shop-service
|
v
EndpointSlices
|
v
Pod IP Addresses
|
v
Envoy Gateway
|
v
Envoy Proxy Configuration
Envoy Gateway watches the relevant Service and EndpointSlice resources and uses endpoint information when generating Envoy configuration.
An important implementation detail:
By default, Envoy Gateway uses Endpoint routing. In this mode, Envoy receives the backend Pod endpoints and connects directly to those endpoints.
The backend request does not need to pass through the Service ClusterIP or kube-proxy.
However, Envoy Gateway also supports Service routing mode. In that mode, Envoy connects to the Kubernetes Service ClusterIP instead.
Therefore, direct Pod endpoint routing is the default behavior, not a universal rule for every Envoy Gateway configuration.
What happens when a backend Pod is replaced?
Consider a backend Service with two available Pods:
shop-service
|
|---- Pod A (10.0.1.10)
|
|---- Pod B (10.0.1.11)
Now imagine Pod A is deleted and Kubernetes creates a replacement:
shop-service
|
|---- Pod B (10.0.1.11)
|
|---- Pod C (10.0.1.15)
Kubernetes updates the EndpointSlice to reflect the current endpoints.
Envoy Gateway observes the updated endpoint information and generates the relevant endpoint configuration, which is delivered to Envoy Proxy through EDS when that discovery mechanism is used.
This allows Envoy Proxy to route traffic to the updated set of endpoints without requiring you to manually change the HTTPRoute.
7. Troubleshooting: When Gateway API Routing Doesn't Work
Understanding the translation process also makes troubleshooting easier.
Here are four useful stages to investigate.
1. Check Gateway and HTTPRoute status
kubectl get gateway
kubectl describe gateway example-gateway
kubectl describe httproute shop-route
Check the Gateway address, whether it has been programmed successfully, and the conditions under status.parents[] for the HTTPRoute.
Two important HTTPRoute conditions are:
-
Accepted: Indicates whether the route has been accepted by its parent Gateway. -
ResolvedRefs: Indicates whether the route's referenced objects, such as backend Services and ports, have been resolved successfully.
Important distinction: ResolvedRefs=True does not guarantee that backend Pods are healthy or available.
A Service can exist and its port can be valid while having zero ready endpoints. In that situation, the references may be resolved successfully, but requests can still fail at runtime because there are no healthy upstream endpoints.
Also check observedGeneration. Each status condition includes an observedGeneration value (under status.conditions[] for a Gateway, and under status.parents[].conditions[] for an HTTPRoute).
Compare it with the resource's metadata.generation. If they differ, the controller may not yet have processed the latest resource changes, and the status you are reading may describe an older version.
2. Check backend Service and EndpointSlices
kubectl get svc shop-service
kubectl get endpointslices
kubectl get pods -o wide
Check whether the Service exists and whether its EndpointSlices contain the expected ready endpoints.
Also check the observedGeneration field under status.conditions[].
Compare it with the resource's metadata.generation. If they differ, the controller may not yet have processed the latest resource changes.
3. Inspect Envoy Proxy configuration
For releases that support the following command:
egctl config envoy-proxy route
This helps inspect the route configuration currently loaded by Envoy Proxy.
You can also inspect other configuration types, such as listeners and clusters, using the corresponding egctl config envoy-proxy subcommands.
To inspect Envoy Gateway's in-memory configuration, documented releases also provide:
egctl config envoy-gateway all -n envoy-gateway-system
Check the documentation for your installed version because egctl commands and options can change.
4. Check controller and proxy logs
kubectl logs -n envoy-gateway-system deployment/envoy-gateway
Use the appropriate Envoy Proxy Pod name to inspect proxy logs as well.
These checks help narrow down whether the problem is related to route attachment, reference resolution, endpoint availability, translation, or the configuration loaded by Envoy.
8. Putting Everything Together
When you create a Gateway and HTTPRoute:
- Envoy Gateway watches the Kubernetes resources.
- It validates the Gateway and route configuration.
- It resolves backend references.
- It translates the Gateway API resources into an Intermediate Representation.
- It generates the required Envoy configuration.
- It delivers that configuration to Envoy Proxy through xDS.
- Envoy Proxy uses listeners, routes, clusters, and endpoints to process incoming traffic.
- Endpoint changes are reflected in the proxy configuration as Kubernetes updates its resources.
The key idea is that Gateway API defines the desired traffic routing, Envoy Gateway translates that intent, and Envoy Proxy executes the resulting configuration.
Once you understand this flow, Gateway API becomes much easier to troubleshoot because you know where each part of the configuration comes from.
What's Next?
In the next article, we'll explore:
Kubernetes Gateway API Traffic Splitting: Implementing Canary Releases with Weighted Routing
We'll see how to distribute traffic between stable and canary application versions using weighted HTTPRoute backend references.
Discussion
Have you worked with Envoy Proxy or xDS configuration before? Which part of the Gateway API translation process did you find most interesting?
Top comments (2)
The controller translation layer is where configuration intent becomes runtime behavior, so status conditions and generated-resource visibility are essential. Being able to correlate an HTTPRoute change to the resulting proxy config and rollout state shortens the gap between declarative YAML and an observable failure.
Absolutely! That's exactly the point. Just seeing HTTPRoute as Accepted doesn't mean everything is working as expected. Being able to trace what happens after that, all the way to the actual Envoy configuration, makes troubleshooting much easier. Thanks for adding this perspective!