The previous lesson taught you Gateway API as a specification—the resources, the three-tier model, the role separation. But specifications do not route traffic. You need a controller that watches Gateway API resources and configures actual proxies to handle requests.
Envoy Gateway is that controller. Built specifically for Gateway API (not retrofitted from an older project), it uses Envoy Proxy as its data plane—the same battle-tested proxy that powers Istio, AWS App Mesh, and countless production deployments. When you create a Gateway resource, Envoy Gateway deploys Envoy proxies configured to match your specification.
This lesson installs Envoy Gateway in your Kubernetes cluster. By the end, you will have a working GatewayClass, understand how requests flow from your Gateway definition to actual traffic handling, and create your first Gateway resource.
Before installing anything, you need to understand what Envoy Gateway deploys and how the pieces interact. The architecture has two distinct planes.
The control plane runs in the envoy-gateway-system namespace. It consists of a single deployment that performs three functions:
The control plane does not handle traffic. It manages configuration.
When you create a Gateway resource, the Infra Manager deploys Envoy proxy pods. These proxies receive configuration from the control plane via the xDS protocol—a gRPC-based streaming API that Envoy uses for dynamic configuration.
The beauty of xDS: configuration changes happen without restarting proxies. Update an HTTPRoute, and within seconds the control plane pushes new routing configuration to all Envoy instances via xDS streams.
xDS (x Discovery Service) is how Envoy receives configuration:
You do not interact with xDS directly. You write Gateway API resources; Envoy Gateway translates them to xDS and streams updates to proxies.
Gateway API CRDs define the resource types (GatewayClass, Gateway, HTTPRoute) that Kubernetes will recognize. Install them before Envoy Gateway.
Install the standard Gateway API CRDs:
Output:
Verify the CRDs are installed:
Output:
The standard-install.yaml includes the core resources that reached General Availability (GA) in Gateway API v1.0:
Experimental resources (GRPCRoute, TCPRoute, etc.) require a separate installation if needed.
Envoy Gateway is distributed as a Helm chart from Docker Hub. The chart installs the control plane and creates the GatewayClass automatically.
Install Envoy Gateway v1.6.1:
Output:
The --create-namespace flag creates envoy-gateway-system if it does not exist.
Wait for the controller to become available:
Output:
Check the running pods:
Output:
A single pod runs the control plane. This is the component that watches Gateway API resources and manages the data plane.
Envoy Gateway automatically creates a GatewayClass named eg (short for "Envoy Gateway"). This class tells Kubernetes that Envoy Gateway will handle any Gateway referencing it.
Check the GatewayClass:
Output:
The ACCEPTED: True status means the controller acknowledged this class. If you see False or no status, the controller is not running correctly.
View the GatewayClass details:
Output:
The controllerName field is the key. Any Gateway referencing gatewayClassName: eg will be handled by the controller with this name.
Now create a Gateway that uses the eg GatewayClass. This Gateway will listen for HTTP traffic on port 80.
Create task-api-gateway.yaml:
Apply the Gateway:
Output:
Check the Gateway status:
Output:
The PROGRAMMED: True status means Envoy Gateway successfully created the data plane resources.
View detailed status:
Output:
The status shows:
When you created the Gateway, the Infra Manager deployed data plane resources. Examine them:
Check for Envoy proxy pods:
Output:
Envoy Gateway creates a Deployment for each Gateway. The pod runs the Envoy proxy that handles traffic.
Check the Service:
Output:
The Service type is LoadBalancer by default. On Docker Desktop, the external IP may show <pending> until you access it via port-forward or the LoadBalancer assigns an IP.
The default Envoy deployment works for development. For production, you may need to customize resource limits, replicas, or add pod anti-affinity. Envoy Gateway provides the EnvoyProxy CRD for this.
Create envoy-proxy-config.yaml:
Reference the EnvoyProxy from GatewayClass:
To use this configuration, create production-gatewayclass.yaml:
Gateways using gatewayClassName: eg-production will deploy 3 Envoy replicas with production resource limits and anti-affinity rules spreading pods across nodes.
The control plane accepted the Gateway but failed to deploy the data plane.
Check controller logs:
Output (example error):
Common causes:
The controller is not running or not watching this GatewayClass.
Verify the controller is running:
Verify the controller name matches:
Output:
This must match the controller Envoy Gateway advertises.
On Docker Desktop or clusters without a LoadBalancer controller, external IPs stay <pending>.
Use port-forward for local access:
Now access http://localhost:8080.
Install the standard Gateway API CRDs and verify:
Expected: Four CRDs listed (gatewayclasses, gateways, httproutes, referencegrants)
Install Envoy Gateway and verify the controller is running:
Expected: envoy-gateway pod in Running state
Check that the eg GatewayClass was created automatically:
Expected: eg class with True for Accepted condition
Create a Gateway and verify it becomes PROGRAMMED:
Expected: Gateway shows PROGRAMMED: True
Find the Envoy proxy pods and Service created for your Gateway:
Expected: One Envoy pod running, one LoadBalancer Service
You built a traffic-engineer skill in Lesson 0. Based on what you learned about Envoy Gateway:
Your skill should now include Envoy Gateway installation:
What verification steps are essential?
Your skill should include common issues:
For production deployments, your skill should ask:
If the answer is "production," generate an EnvoyProxy CRD with the custom GatewayClass.
Ask your traffic-engineer skill to explain the architecture:
What you're learning: The internal mechanics of Envoy Gateway. AI can explain the sequence: Gateway Controller watches -> Translator converts to xDS -> xDS Server streams to Envoy proxies. Compare this to the architecture diagram in this lesson.
Review what AI provided. Check:
If anything is missing or incorrect, tell AI what you learned in this lesson and ask it to refine its explanation.
Tell AI about your production requirements:
What you're learning: Working with AI to generate Kubernetes resources. AI should produce an EnvoyProxy with replicas: 3, resource limits, and pod anti-affinity. Verify the YAML matches what you learned in the EnvoyProxy section.
If AI's EnvoyProxy YAML differs from the lesson, work through the differences:
This iteration—AI suggests, you validate, AI refines—is how production configurations emerge.
When installing Envoy Gateway in shared or production clusters, coordinate with your platform team. The GatewayClass and CRDs are cluster-scoped resources. Multiple installations of Gateway API CRDs can conflict if versions differ. Always check for existing installations with kubectl get crds | grep gateway before applying new CRDs.