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:

  1. Envoy Gateway observes the Gateway resource.
  2. It checks the referenced GatewayClass and listener configuration.
  3. It provisions an Envoy Proxy workload.
  4. It creates a Service exposing the proxy, which is type LoadBalancer by default.
  5. 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 as shop.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:

  1. Envoy Gateway watches the Kubernetes resources.
  2. It validates the Gateway and route configuration.
  3. It resolves backend references.
  4. It translates the Gateway API resources into an Intermediate Representation.
  5. It generates the required Envoy configuration.
  6. It delivers that configuration to Envoy Proxy through xDS.
  7. Envoy Proxy uses listeners, routes, clusters, and endpoints to process incoming traffic.
  8. 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?