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.

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.

Expand for instructions

Install the Gateway API CRDs and Envoy Gateway using Helm:

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

Notice

Gateway Namespace Mode is currently an alpha feature. We recommend against using it in production workloads until it reaches beta status.

For status updates or to provide feedback, please follow our GitHub issues.

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.

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

Notice

Overview

Standalone Deployment Mode

Notice

Quick Start

Running locally on the host machine

Use egctl

egctl config

egctl experimental status

Gateway – `values.yaml` Configuration