Operations on Envoy Gateway

Customize EnvoyProxy

Mon, 01 Jan 0001 00:00:00 +0000

Envoy Gateway provides an EnvoyProxy CRD that can be linked to the ParametersRef in a Gateway and GatewayClass, allowing cluster admins to customize the managed EnvoyProxy Deployment and Service. To learn more about GatewayClass and ParametersRef, please refer to Gateway API documentation.

Note: We recommend creating a EnvoyProxy resource before creating a Gateway or GatewayClass that references it to avoid temporary disruption.

Prerequisites

Follow the steps below to install Envoy Gateway and the example manifest. Before proceeding, you should be able to query the example backend using HTTP.

Deploy Envoy Gateway in Air-Gapped Environments

Mon, 01 Jan 0001 00:00:00 +0000

Deploying the Envoy Gateway in an air-gapped environment using a Helm chart requires careful configuration of the values.yaml file as well as adjustments when deploying a Gateway resource.

You will need to specify custom image repositories for the following components in the Helm chart. This can be done on a global level or image level.

Gateway
Ratelimit

Gateway – `values.yaml` Configuration

Example done in image level:

deployment:
 envoyGateway:
 image:
 repository: custom-cr.internal.io/envoyproxy/gateway
 tag: v1.4.1

It’s also possible to define the registry on a global level:

Deployment Mode

Mon, 01 Jan 0001 00:00:00 +0000

Deployment modes

One GatewayClass per Envoy Gateway Controller

An Envoy Gateway is associated with a single GatewayClass resource under one controller. This is the simplest deployment mode and is suitable for scenarios where each Gateway needs to have its own dedicated set of resources and configurations.

Multiple GatewayClasses per Envoy Gateway Controller

An Envoy Gateway is associated with multiple GatewayClass resources under one controller.
Support for accepting multiple GatewayClasses was added here.

Separate Envoy Gateway Controllers

If you’ve instantiated multiple GatewayClasses, you can also run separate Envoy Gateway controllers in different namespaces, linking a GatewayClass to each of them for multi-tenancy. Please follow the example Multi-tenancy.

Gateway Namespace Mode

Mon, 01 Jan 0001 00:00:00 +0000

Overview

In standard deployment mode, Envoy Gateway creates all data plane resources in the controller namespace (typically envoy-gateway-system).

The motivation behind this was to operate with minimum permissions needed to be given for Envoy Gateway controller, as the control plane and data plane was deployed in the same namespace.

Gateway Namespace Mode changes this behavior by placing Envoy Proxy data plane resources like Deployments, Services and ServiceAccounts in each Gateway’s namespace, which provides stronger isolation and multi-tenancy compared to the Controller Namespace mode, as it isolates Envoy proxy data plane across different tenants. This distributed architecture requires additional RBAC permissions for the Envoy Gateway controller to manage Kubernetes resources across multiple namespaces.

Graceful Shutdown and Hitless Upgrades

Mon, 01 Jan 0001 00:00:00 +0000

Envoy Gateway enables zero-downtime deployments through graceful connection draining during pod termination.

Overview

The shutdown manager sidecar coordinates graceful connection draining during pod termination, providing:

Zero-downtime rolling updates
Configurable drain timeouts
Automatic health check failure to remove pods from load balancer rotation

Shutdown Process

Kubernetes sends SIGTERM to the pod
Shutdown manager fails health checks via /healthcheck/fail
- This causes Kubernetes readiness probes to fail
- External load balancers and services stop routing new traffic to the pod
- Existing connections continue to be served while draining
Connection monitoring begins, polling server.total_connections
Process exits when connections reach zero or drain timeout is exceeded

Configuration

Graceful shutdown behavior includes default values that can be overridden using the EnvoyProxy resource. The EnvoyProxy resource can be referenced in two ways:

Standalone Deployment Mode

Mon, 01 Jan 0001 00:00:00 +0000

Notice

Standalone mode is an experimental feature, please DO NOT use it in production.

Envoy Gateway also supports running in standalone mode. In this mode, Envoy Gateway does not need to rely on Kubernetes and can be deployed directly on bare metal or virtual machines.

Currently, Envoy Gateway only support the file provider and the host infrastructure provider combinations.

The file provider will configure the Envoy Gateway to get all gateway-api resources from file system.
The host infrastructure provider will configure the Envoy Gateway to deploy one Envoy Proxy as a host process.

Quick Start

Running locally on the host machine

In this quick-start, we will run Envoy Gateway in standalone mode with the file provider and the host infrastructure provider.

Use egctl

Mon, 01 Jan 0001 00:00:00 +0000

egctl is a command line tool to provide additional functionality for Envoy Gateway users.

Follow the instructions here to install egctl.

egctl config

The egctl config subcommand provides tools for viewing and validating the Envoy Proxy and Envoy RateLimit configuration configured in Envoy Proxy.

Here’s an example of retrieving the xDS Route Configuration from all the proxies.

~ egctl config envoy-proxy route
{
 "envoy-gateway-system": {
 "envoy-default-eg-e41e7b31-6d749cdb85-hcfrk": {
 "@type": "type.googleapis.com/envoy.admin.v3.RoutesConfigDump",
 "dynamicRouteConfigs": [
 {
 "lastUpdated": "2025-05-22T17:51:06.237Z",
 "routeConfig": {
 "@type": "type.googleapis.com/envoy.config.route.v3.RouteConfiguration",
 "ignorePortInHostMatching": true,
 "name": "default/eg/http",
 "virtualHosts": [
 {
 "domains": [
 "www.example.com"
 ],
 "metadata": {
 "filterMetadata": {
 "envoy-gateway": {
 "resources": [
 {
 "kind": "Gateway",
 "name": "eg",
 "namespace": "default",
 "sectionName": "http"
 }
 ]
 }
 }
 },
 "name": "default/eg/http/www_example_com",
 "routes": [
 {
 "match": {
 "prefix": "/"
 },
 "metadata": {
 "filterMetadata": {
 "envoy-gateway": {
 "resources": [
 {
 "kind": "HTTPRoute",
 "name": "backend",
 "namespace": "default"
 }
 ]
 }
 }
 },
 "name": "httproute/default/backend/rule/0/match/0/www_example_com",
 "route": {
 "cluster": "httproute/default/backend/rule/0",
 "upgradeConfigs": [
 {
 "upgradeType": "websocket"
 }
 ]
 }
 }
 ]
 }
 ]
 },
 "versionInfo": "bc44981323d08bcb24abad6867942912675bb35bb674f2ee9ae866efbe1375dd"
 }
 ],
 "staticRouteConfigs": [
 {
 "lastUpdated": "2025-05-22T17:51:06.198Z",
 "routeConfig": {
 "@type": "type.googleapis.com/envoy.config.route.v3.RouteConfiguration",
 "name": "local_route",
 "virtualHosts": [
 {
 "domains": [
 "*"
 ],
 "name": "prometheus_stats",
 "routes": [
 {
 "match": {
 "headers": [
 {
 "name": ":method",
 "stringMatch": {
 "exact": "GET"
 }
 }
 ],
 "path": "/stats/prometheus"
 },
 "route": {
 "cluster": "prometheus_stats"
 }
 }
 ]
 }
 ]
 }
 },
 {
 "lastUpdated": "2025-05-22T17:51:06.219Z",
 "routeConfig": {
 "@type": "type.googleapis.com/envoy.config.route.v3.RouteConfiguration",
 "name": "ready_route",
 "virtualHosts": [
 {
 "domains": [
 "*"
 ],
 "name": "ready_route",
 "routes": [
 {
 "directResponse": {
 "status": 500
 },
 "match": {
 "prefix": "/"
 }
 }
 ]
 }
 ]
 }
 }
 ]
 }
 }
}

egctl experimental status

This subcommand allows users to show the summary of the status of specific or all resource types, in order to quickly find out the status of any resources.

Operations on Envoy Gateway

Customize EnvoyProxy

Prerequisites

Deploy Envoy Gateway in Air-Gapped Environments

Gateway – values.yaml Configuration

Deployment Mode

Deployment modes

One GatewayClass per Envoy Gateway Controller

Multiple GatewayClasses per Envoy Gateway Controller

Separate Envoy Gateway Controllers

Gateway Namespace Mode

Overview

Graceful Shutdown and Hitless Upgrades

Overview

Shutdown Process

Configuration

Standalone Deployment Mode

Notice

Quick Start

Running locally on the host machine

Use egctl

egctl config

egctl experimental status

Gateway – `values.yaml` Configuration