Reference¶
Scope
Look-up facts for Envoy Gateway: version and support matrix, release history, CRDs and attachment targets, controller configuration flags, ports, egctl commands, generated xDS mapping, security controls, and advisories. For tasks see How-to Guides. For how it works see Explanation.
Compatibility Matrix¶
Each EG minor ships with and is tested against exactly one Envoy Proxy minor version. Source: Compatibility Matrix (checked 2026-09-25).
| Envoy Gateway | Envoy Proxy | Gateway API | Kubernetes (tested) | End of Life |
|---|---|---|---|---|
| v1.9 | distroless-v1.39.x | v1.6.1 | v1.33, v1.34, v1.35, v1.36 | 2027-02-14 |
| v1.8 | distroless-v1.38.x | v1.5.1 | v1.32, v1.33, v1.34, v1.35 | 2026-11-08 |
| v1.7 | distroless-v1.37.x | v1.4.1 | v1.32, v1.33, v1.34, v1.35 | 2026-08-05 (EOL) |
| v1.6 | distroless-v1.36.x | v1.4.0 | v1.30, v1.31, v1.32, v1.33 | 2026-05-13 (EOL) |
| v1.5 | distroless-v1.35.x | v1.3.0 | v1.30, v1.31, v1.32, v1.33 | 2026-02-13 (EOL) |
| v1.4 | distroless-v1.34.x | v1.3.0 | v1.30, v1.31, v1.32, v1.33 | 2025-11-13 (EOL) |
| v1.0 | distroless-v1.29.x | v1.0.0 | v1.26, v1.27, v1.28, v1.29 | 2024-09-13 (EOL) |
main (dev) |
dev-latest | v1.6.1 | v1.34, v1.35, v1.36, v1.37 | n/a |
Pinning a different Envoy image
Setting image on the EnvoyProxy resource pins the data plane independently of the control plane. A different Envoy minor is untested, and a rejected config stays silent until a proxy restarts. Prefer imageRepository (EG supplies the tag) and watch the xdsNACKTotal metric (added in v1.9).
Release History¶
| Release | Date | Notes |
|---|---|---|
| v1.9.1 | 2026-08-28 | Reverts the v1.9.0 0s SDS/RDS initial fetch timeout; CVE-2026-47775 fix; users on v1.8.x skip v1.9.0 |
| v1.8.4 | 2026-08-28 | Same security fixes backported; Envoy 1.38.4, Go 1.26.7 |
| v1.9.0 | 2026-08-14 | Gateway API v1.6.1, CSRF, CEL authorization, ListenerSet policy targets, remote infra provider |
| v1.7.5 | 2026-07-08 | Last v1.7 patch found in the release notes (v1.7 EOL 2026-08-05) |
| v1.8.3 | 2026-07-22 | Lua moved to listener-level filters |
| v1.8.2 | 2026-06-30 | Patch |
| v1.8.1 | 2026-06-04 | Gateway API safe-upgrade ValidatingAdmissionPolicy moved into Helm templates |
| v1.8.0 | 2026-05-12 | Dynamic Modules, chained extension managers, EnvoyProxy mergeType, GeoIP authorization |
| v1.7.3 | 2026-05-09 | Go 1.25.10, gRPC-Go CVE-2026-33186 fix |
| v1.7.0 | 2026-02-05 | Experimental XListenerSet, Lua hardening, custom_response filter first |
| v1.6.0 | 2025-11-10 | Gateway API v1.4.0 |
| v1.5.0 | 2025-08-08 | Gateway API v1.3.0 |
| v1.0.0 | 2024-03-13 | First GA release |
Source: release notes index. The GitHub release/v1.9 branch VERSION file reads v1.9.1 and release/v1.8 reads v1.8.4 (checked 2026-09-25).
CRDs¶
Gateway API resources used by EG¶
| Kind | API version (Gateway API v1.6) | Channel |
|---|---|---|
| GatewayClass, Gateway, HTTPRoute, GRPCRoute | gateway.networking.k8s.io/v1 |
Standard |
| ReferenceGrant | gateway.networking.k8s.io/v1 (promoted in Gateway API v1.5; v1beta1 still served) |
Standard |
| BackendTLSPolicy | gateway.networking.k8s.io/v1 (GA since Gateway API v1.4) |
Standard |
| TLSRoute, ListenerSet | gateway.networking.k8s.io/v1 (GA since Gateway API v1.5) |
Standard |
| TCPRoute, UDPRoute | gateway.networking.k8s.io/v1 (GA in v1.6; v1alpha2 deprecated) |
Standard |
Envoy Gateway extension resources¶
All EG resources use gateway.envoyproxy.io/v1alpha1.
| Kind | Purpose | Attach targets | Enabled by default |
|---|---|---|---|
| EnvoyGateway | Controller config (loaded from the envoy-gateway-config ConfigMap, not a CRD) |
n/a | n/a |
| EnvoyProxy | Envoy deployment, service, bootstrap, telemetry, mergeGateways, mergeBackends |
GatewayClass parametersRef, Gateway infrastructure.parametersRef |
Yes |
| ClientTrafficPolicy | Downstream TLS, client IP detection, timeouts, HTTP/1-2-3, headers | Gateway, listener (sectionName), ListenerSet (v1.9) |
Yes |
| BackendTrafficPolicy | LB, retries, circuit breaker, health checks, rate limits, compression, response override | Gateway, xRoute, ListenerSet (v1.9) | Yes |
| SecurityPolicy | JWT, OIDC, API key, Basic auth, ExtAuth, authorization, CORS, CSRF (v1.9) | Gateway, HTTPRoute, GRPCRoute, TCPRoute, ListenerSet (v1.9) | Yes |
| EnvoyExtensionPolicy | Wasm, ExtProc, Lua, Dynamic Modules | Gateway, xRoute, ListenerSet (v1.9) | Yes (Lua needs enableLua since v1.9) |
| EnvoyPatchPolicy | JSON patch of generated xDS | GatewayClass, Gateway | No (enableEnvoyPatchPolicy) |
| Backend | FQDN, IP, Unix socket, or DynamicResolver endpoints with TLS settings |
Referenced as a backendRef |
No (enableBackend) |
| HTTPRouteFilter | EG route filters (regex host/path rewrite, direct response, credential injection) | extensionRef from HTTPRoute or GRPCRoute (v1.9) rules |
Yes |
Sources: Concepts, Gateway API Extensions, envoygateway_types.go.
EnvoyGateway extensionApis Flags¶
| Field | Default | Effect |
|---|---|---|
enableEnvoyPatchPolicy |
false |
Reconcile EnvoyPatchPolicy. Upstream warns this can lead to complete compromise, because patch authors can inject arbitrary proxy config. |
enableBackend |
false |
Reconcile the Backend CRD |
enableLua |
false |
Allow Lua EnvoyExtensionPolicies (since v1.9) |
disableLua |
unset | Deprecated in v1.9 in favor of enableLua |
enableSDSSecretRef |
false |
Allow gateway.envoyproxy.io/sds Secrets that point at an external SDS server |
Helm sets these through config.envoyGateway.extensionApis.*, for example --set config.envoyGateway.extensionApis.enableBackend=true.
Rate Limit Fields (BackendTrafficPolicy)¶
| Field | Notes |
|---|---|
rateLimit.local.rules[] |
Per-proxy token bucket, no external service |
rateLimit.global.rules[] |
Shared counters through envoy-ratelimit plus Redis |
rateLimit.type |
Deprecated. Set global and/or local directly; both may be combined. |
rules[].clientSelectors[] |
Match on headers, methods, path, sourceCIDR, queryParams, each with invert |
rules[].limit.requests / unit |
Units: Second, Minute, Hour, Day, Week (v1.9), Month, Year |
rules[].limit.fromMetadata |
v1.9: take the limit from dynamic metadata, with a static fallback |
rules[].cost, shared, shadowMode |
Request/response cost, shared buckets across routes, log-only mode |
EnvoyGateway rateLimit.backend.redis.url |
Redis endpoint for global limits; urlRef (v1.9) reads it from a Secret |
Ports¶
| Port | Component | Purpose |
|---|---|---|
| 18000 | envoy-gateway | xDS gRPC server (mTLS) that Envoy connects to |
| 19000 | Envoy (127.0.0.1) | Admin interface, localhost only |
| 19001 | Envoy | Prometheus stats at /stats/prometheus |
| 19003 | Envoy | Readiness probe at /ready |
Sources: bootstrap.go constants (EnvoyAdminPort, DefaultXdsServerPort, EnvoyStatsPort, EnvoyReadinessPort). Gateway listeners on privileged ports (below 1024) are mapped internally to an unprivileged container port, so the Service keeps the requested port while Envoy runs without root.
Defaults Worth Knowing¶
| Setting | Default |
|---|---|
| Envoy Deployment replicas | 1 (DefaultDeploymentReplicas) |
| xDS transport | Delta ADS over gRPC (api_type: DELTA_GRPC in the bootstrap) |
| Graceful drain on shutdown | shutdown.drainTimeout 60s |
| xDS server max receive message | 32 MiB (raised from 4 MiB in v1.9) |
| Tracing client sampling | 0% since v1.9 (was 100%) |
| Upstream TLS max version | TLS 1.3 (v1.9 fix; was capped at 1.2) |
| EnvoyProxy config precedence | Gateway > GatewayClass > EnvoyGateway default, mergeType: Replace unless set (v1.8+) |
egctl Commands¶
| Command | Purpose |
|---|---|
egctl x translate --from gateway-api --to xds -f <file> |
Offline translation of manifests to xDS (-t route limits the type, --add-missing-resources stubs references) |
egctl config envoy-proxy <type> -n <ns> [pod] |
Dump live config from a managed proxy; <type> is all, listener, route, cluster, and similar |
egctl config envoy-gateway all -n envoy-gateway-system |
Controller in-memory resources through the admin config dump (v1.8+) |
egctl x status all -A / egctl x status httproute --quiet -A |
Summarize status conditions across resources |
egctl x dashboard envoy-proxy -n <ns> <pod> |
Port-forward and open the Envoy admin dashboard |
egctl x install / egctl x uninstall |
Install or remove EG without Helm (--skip-crds, --only-crds, --with-crds) |
Source: egctl task.
Generated xDS by Resource¶
| Resource | xDS resources generated |
|---|---|
| Gateway listener | Listener, filter chain, downstream TLS context (SDS secret) |
| HTTPRoute / GRPCRoute rule | Route configuration, virtual host, route, cluster, ClusterLoadAssignment |
| SecurityPolicy (JWT) | jwt_authn HTTP filter plus per-route config; provider names content-derived since v1.9 |
| SecurityPolicy (OIDC) | One oauth2 HTTP filter in the HCM plus route typed_per_filter_config (v1.8+) |
| SecurityPolicy (ExtAuth) | ext_authz filter and a cluster for the auth service |
| BackendTrafficPolicy | Cluster LB policy, circuit breakers, health checks, outlier detection, rate limit descriptors |
| BackendTrafficPolicy (global rate limit) | ratelimit filter; shared-only rules in typedPerFilterConfig since v1.9 |
| EnvoyExtensionPolicy (Lua) | Listener-level Lua filters since v1.8.3 (previously LuaPerRoute) |
Security Controls Summary¶
| Layer | Mechanism | Resource |
|---|---|---|
| Client to gateway TLS | TLS termination (or passthrough through TLSRoute) | Gateway listener certificateRefs |
| Client certificates | mTLS client validation, CRLs, allowExpiredCertificate (v1.9) |
ClientTrafficPolicy tls.clientValidation |
| Gateway to backend TLS | TLS origination and SAN validation | BackendTLSPolicy (Gateway API v1) |
| Gateway to backend mTLS | Client certificate plus CA validation | Backend tls.clientCertificateRef or EnvoyProxy backendTLS |
| Authentication | JWT, OIDC, API key, Basic auth | SecurityPolicy |
| External authorization | gRPC or HTTP ext_authz | SecurityPolicy extAuth |
| Authorization | Allow/deny rules on principals, headers, CIDR, GeoIP, CEL (v1.9) | SecurityPolicy authorization |
| Browser protections | CORS, CSRF (v1.9) | SecurityPolicy cors, csrf |
| Abuse control | Local and global rate limiting | BackendTrafficPolicy rateLimit |
BackendTLSPolicy Validation Fields¶
| Field | Purpose |
|---|---|
hostname |
SNI hostname sent to the backend, also used for certificate validation (required) |
caCertificateRefs |
ConfigMap or Secret references with CA bundles |
wellKnownCACertificates: System |
Use the system trust store instead of refs; since v1.9 all such policies share one system_ca_certificates SDS secret |
subjectAltNames[] |
Objects with type: Hostname or type: URI and the matching hostname or uri value |
Security Advisories and Hardening Changes¶
| Version | Item |
|---|---|
| v1.9.1 / v1.8.4 | CVE-2026-47775: OAuth2/OIDC session cookies now AES-256-GCM; existing CBC sessions are invalidated |
| v1.9.1 / v1.8.4 | GHSA-w42f-28h3-998w: tenant EnvoyProxy securityContext replaced hardened defaults (confused deputy, PSA escape) |
| v1.9.1 / v1.8.4 | OCI Wasm pulls no longer fall back to plain HTTP; HTTP OIDC issuer URLs rejected |
| v1.9.0 | xDS server authentication bypass in GatewayNamespace mode fixed; controller runs with a read-only root filesystem |
| v1.7.3 | gRPC-Go CVE-2026-33186 (authorization bypass) through dependency bump |
| v1.7.0 | Lua EnvoyExtensionPolicy sandboxing and resource limits |
Sources: v1.9.1 notes, v1.8.4 notes, v1.9 announcement, v1.7.3 notes.
Agent Router (formerly Envoy AI Gateway) Compatibility¶
| Agent Router | Envoy Gateway | Gateway API | Kubernetes |
|---|---|---|---|
| v1.1.x (v1.1.0 tagged 2026-08-21) | Not listed: the matrix, including the copy in the v1.1.0 tag, has no v1.1.x row (checked 2026-09-28). The v1.1.0 go.mod builds against EG v1.8.1 |
Not listed (go.mod: Gateway API v1.5.1) |
Not listed |
| v1.0.x (2026-06) | v1.8.1+ (Envoy v1.38.x) | v1.5.x | v1.32+ |
| v0.7.x | v1.8.x+ | v1.5.x | v1.32+ |
| v0.6.x | v1.7.x+ | v1.4.x | v1.32+ |
Source: Agent Router compatibility page (read from the site/docs/compatibility.md file in the repository).
Release Benchmark Report¶
Each EG release ships a Nighthawk benchmark (benchmark_report.zip on the GitHub release), browsable in the site's Benchmark Report Explorer (source). The test (ScaleHTTPRoute) uses one Gateway and scales HTTPRoutes up and then down. v1.9.1 run (2026-08-28): 100 connections, 90 s per step, 1000m CPU and 2000Mi memory limits. Figures below are the scale-up steps, taken from the explorer's data file for v1.9.1 (checked 2026-09-28).
| HTTPRoutes (routes per hostname) | Measured RPS | p50 / p99 latency (ms) | Controller memory max (MiB) | Proxy memory max (MiB) | Proxy CPU mean (%) |
|---|---|---|---|---|---|
| 10 (2) | 400 | 0.46 / 1.51 | 138 | 21 | 9.8 |
| 100 (20) | 1,999 | 0.46 / 1.64 | 149 | 29 | 34.4 |
| 300 (60) | 3,200 | 0.60 / 3.02 | 166 | 48 | 72.2 |
| 500 (100) | 3,998 | 0.69 / 25.92 | 189 | 69 | 82.0 |
| 1,000 (200) | 5,034 | 62.69 / 95.29 | 260 | 105 | 99.1 |
Read these as a regression baseline for one small, CPU-limited proxy, not as capacity limits. At 1,000 routes the proxy sits near its 1-core limit, which is why p50 latency jumps. After scaling back down, controller memory stayed at 160-260 MiB and proxy memory at about 103 MiB, so size for the peak route count you have reached. Benchmark your own filters and payloads before capacity planning.
Since v1.9, EndpointSlice field indexing is on by default and can raise controller memory in clusters with many EndpointSlices. EnvoyProxy.spec.mergeBackends (v1.9, off by default) reduces cluster count and stats cardinality.