Release Announcement TEG 1.9

Date: August 20, 2026

info

TEG v1.9.1 is supported until 1st August 2027. TEG 1.8.x is supported until 1st May 2027 — plan your upgrade before that date. See Support for the full support matrix.

New Feature Highlights

Tetrate Enterprise Gateway for Envoy (TEG) v1.9.1 is built on Envoy Gateway 1.9.0, Envoy 1.39.0, and Gateway API v1.6.1. It introduces three distinct TEG editions (community, enterprise, and enterprise FIPS), makes the Web Application Firewall available out of the box on a publicly pullable data-plane image, and makes the chart's GatewayClass configurable so TEG can be installed alongside an existing Envoy Gateway. Upstream brings native CSRF protection, CEL-based authorization, ListenerSet as a policy target across all four xPolicy kinds, cluster deduplication for shared backends, and a large set of correctness fixes across TLS secret handling, status reporting, and CRD-optional clusters.

tip

We recommend upgrading directly from TEG 1.8.x to v1.9.1. Platform teams running TEG 1.7.x should first upgrade to 1.8.x before proceeding.

Packaging and Editions

• Three TEG editions: TEG is now published as community, enterprise, and enterprise FIPS. All three are built from the same source, ship the same Helm chart, and expose the same APIs; they differ in where the images are published, whether the phone-home client reports by default, and (for FIPS) the cryptographic libraries used. The community edition is the public default (docker.io/tetrate/teg-envoy-gateway) and includes an always-on phone-home client that reports version and component information used for CVE and update detection. The enterprise editions ship that client off by default — opt in with phoneHome.enabled=true — and are published to credentialed Tetrate registries, from which they also serve their own data-plane Envoy image. Select an edition by pointing deployment.tegEnvoyGateway.image.repository — and, for the enterprise editions, the Envoy proxy image — at that edition's registry. See TEG Editions.
• WAF works out of the box, from a public image: the default data-plane Envoy image bundles the WAF dynamic module and is published to the public docker.io/tetrate/teg-envoy repository, so ExtendedSecurityPolicy works without overriding the Envoy image or holding Tetrate registry credentials. The enterprise and FIPS editions override the Envoy image with their own variant, which bundles the same module — the FIPS variant bundles the FIPS-compliant build of it — so the WAF works out of the box in every edition.
• Single FIPS registry: every Tetrate-built FIPS image is now published to and consumed from fips-containers.teg.tetratelabs.com. The FIPS data-plane Envoy image moved there from the former private registry and is tagged with the TEG release version, for example envoy:distroless-v1.9.1.
• Version-tagged Envoy images: because the dynamic modules are baked in, the data-plane Envoy images are tagged with the TEG release version (distroless-v1.9.0) rather than the upstream Envoy version, and are slightly larger as a result.
• dns-gateway module bundled: the data-plane image now also carries the dns-gateway dynamic module alongside composer (WAF) and ip-restriction.

Install and Operate

• Configurable GatewayClass: the GatewayClass created by the chart now derives its controllerName from gateway-helm.config.envoyGateway.gateway.controllerName — the same key that configures the control plane — so the class and its controller can no longer drift apart. New gatewayClass.name and gatewayClass.enabled values let you rename the class or skip creating it entirely, which makes it possible to run TEG next to an existing Envoy Gateway or TEG installation without the two contending over the same GatewayClass, Gateways, and Envoy Deployments. Defaults are unchanged.
• commonLabels across chart resources: a single commonLabels value applies labels to every resource the chart creates — Deployment, certgen Job, Service, ServiceAccount, RBAC, PodDisruptionBudget, EnvoyProxy, and Redis — for cost allocation, policy targeting, and inventory tooling. certgen.job.pod.labels covers the certgen Job pods.
• certgen Job scheduling: certgen.job.nodeSelector, certgen.job.affinity, and certgen.job.tolerations pin the certgen Job to compatible nodes, which matters on mixed-architecture clusters where the FIPS images are linux/amd64 only.
• Customizable pod security context: the teg-envoy-gateway deployment now applies a default security context and allows it to be customized.
• Helm chart additions from upstream: a startupProbe and configurable liveness/readiness probes on the envoy-gateway Deployment, deployment.envoyGateway.strategy for the update strategy, crds.enabled to disable the CRD dependency, and unhealthyPodEvictionPolicy on the PodDisruptionBudget.
• Redis guidance: the TEG-managed Redis is now explicitly documented as suitable for demos only — a single, non-replicated instance with no persistence, no HA, and no backup. For production, set redis.disabled=true and point the rate limit backend at your own hardened Redis. See Bring your own Redis.
• Redis-backed rate limiting fixed: the bundled Redis no longer attempts RDB snapshots into a read-only filesystem, which previously caused it to reject every write once a snapshot threshold was reached, breaking global rate limiting.

Security Controls

• Native CSRF protection: SecurityPolicy.spec.csrf validates the Origin header of mutating requests against the destination and any additionalOrigins, with shadowFraction for gradual rollout.
• CEL-based authorization: authorization rules in SecurityPolicy accept CEL expressions, and authorization can now match on request path.
• Client IP detection for L4-transparent topologies: ClientTrafficPolicy.spec.clientIPDetection.directSourceIP uses the downstream TCP source address as the client IP, which unlocks clientIPGeoLocations behind an AWS NLB with target-type: instance and externalTrafficPolicy: Local, or an Azure Standard Load Balancer. xForwardedFor.disableXForwardedForAppend disables Envoy's automatic XFF append.
• JWT and OIDC controls: forwardIDToken forwards the OIDC ID token upstream on a configurable header, failedRefetchDuration controls JWKS re-fetch backoff, and failOpen allows requests with a missing or invalid JWT to pass authentication (pair it with an authorization policy).
• mTLS with expired client certificates: tls.clientValidation.allowExpiredCertificate accepts expired client certificates while still validating the CA chain and signature.
• Hardened control plane: the Envoy Gateway controller container runs with a read-only root filesystem, the certgen Job runs with a restricted pod security context, ServiceAccount token automounting is off unless a pod needs it, and an xDS authentication bypass in GatewayNamespaceMode is fixed.
• Go 1.26.6 picks up the latest upstream Go security fixes.

Traffic Handling

• ListenerSet as a policy target: ClientTrafficPolicy, SecurityPolicy, BackendTrafficPolicy, and EnvoyExtensionPolicy can all attach to a ListenerSet, so settings can be applied to a named group of listeners instead of a gateway-wide policy.
• Cluster deduplication for shared backends: EnvoyProxy.spec.mergeBackends (experimental, off by default) lets routes referencing the same backend share one Envoy cluster instead of one per route rule, cutting xDS size, active health-check traffic, and stats cardinality. A selector opts backends in gradually.
• Rate limiting: limits can be sourced from per-request dynamic metadata with fromMetadata, a Week unit is available for global and local limits, the Redis URL can come from a Secret via rateLimit.backend.redis.urlRef, and header matches per rate limit condition were raised from 64 to 128.
• Load balancing and health checks: out-of-band ORCA load reporting via loadBalancer.backendUtilization.outOfBand, a requestBody for HTTP active health checks, and health check event logging in EnvoyProxy and BackendTrafficPolicy.
• Routing and rewrites: GRPCRoute rules can reference an HTTPRouteFilter through an extensionRef filter, HTTPRouteFilter supports PathRegex hostname rewrites, and responseOverride in BackendTrafficPolicy can match on response headers.
• Backend TLS and dynamic proxying: autoSNIFromEndpointHostname derives backend SNI from the endpoint hostname, and a DynamicResolver Backend can be referenced by a TLSRoute for SNI-based dynamic forward proxying.
• Client timeouts: ConnectionInspectionTimeout, RequestHeadersReceivedTimeout, and TLSHandshakeTimeout are now configurable, and headers.host.stripTrailingHostDot normalizes the Host header without an EnvoyPatchPolicy.

Observability and Extensibility

• xDS rejection metric: the new xdsNACKTotal metric counts NACKs from Envoy, labeled by node ID and resource type URL — a direct signal for alerting on configuration Envoy refused to accept.
• Overlapping route detection: a RouteRulesOverlap warning condition surfaces routes silently shadowed by an identical match on the same listener.
• Larger xDS messages: xdsServer.maxReceiveMessageSize is configurable and the default receive limit rose from 4MiB to 32MiB, so large delta xDS requests on reconnect no longer break the stream.
• Extension servers reach further: extension server policies can target resources in other namespaces through ReferenceGrant, and can attach to HTTPRoute, GRPCRoute, and individual rules via sectionName, with the outcome reported in status.ancestors.
• Parameterized Lua: filterContext lets a shared Lua script be parameterized per route through request_handle:filterContext().
• Remote infrastructure provider: define your own infrastructure management strategy instead of the built-in Kubernetes provider.

Performance Improvements

• EndpointSlice lookups now use field indexes when processing backend references.
• BackendTLSPolicy with WellKnownCACertificates: System shares a single SDS secret instead of one per policy, cutting inotify watch usage.
• Translation latency no longer grows quadratically when many policies share one target.

Deprecations

• The disableLua field in extensionApis is deprecated in favor of enableLua. Note that Lua EnvoyExtensionPolicy is now disabled by default — see Breaking Changes.

---

Summary

TEG v1.9.1 tracks Envoy Gateway 1.9.0, Envoy 1.39.0, and Gateway API v1.6.1. The release splits TEG into community, enterprise, and enterprise FIPS editions, publishes a WAF-enabled data plane that needs no credentials, makes the chart's GatewayClass configurable, and lands native CSRF protection, CEL authorization, ListenerSet policy targets, and roughly sixty upstream bug fixes.

• Safe: native CSRF protection, CEL-based authorization, directSourceIP client IP detection, a read-only controller root filesystem, ServiceAccount token automounting off by default, the GatewayNamespaceMode xDS authentication fix, and Go 1.26.6 harden the deployment without configuration changes.
• Safe: TLS correctness fixes — canonical PEM re-encoding, per-listener rejection of mismatched or expired certificate chains, and cert-manager rotation picked up on every handshake — remove failure modes that previously took down TLS for every Gateway sharing a merged proxy.
• Fast: mergeBackends cluster deduplication (experimental, off by default), EndpointSlice field indexes, shared system CA SDS secrets, and the ancestor-capping translation fix reduce xDS size and control-plane CPU on large clusters.
• Profitable: three editions with a public, WAF-enabled data plane let teams evaluate and run TEG without registry credentials, while enterprise customers keep phone home off by default; a configurable GatewayClass allows TEG to be introduced alongside an existing Envoy Gateway instead of requiring a migration.
• Profitable: commonLabels, certgen scheduling controls, urlRef for the rate limit Redis, and chart-level probe and strategy settings remove the most common reasons to fork the chart.

---

Upgrade Guidance

Be aware of the following breaking changes and behavioral differences when upgrading from TEG 1.8 to v1.9.1. Review each item against your current configuration before promoting to production.

Breaking Changes

• Gateway API CRDs must be upgraded to v1.6:
  • Envoy Gateway now reconciles TCPRoute and UDPRoute via gateway.networking.k8s.io/v1. Existing v1alpha2 manifests keep working because both versions are served, but if the v1.6 CRDs are not installed, TCP and UDP routes are silently skipped. The stored version moves to v1; a storage-version migration will be required before v1alpha2 is removed.
  • SessionPersistence.IdleTimeout was removed from HTTPRoute in Gateway API v1.6. Remove sessionPersistence.idleTimeout from your manifests before upgrading the CRDs.
• Lua EnvoyExtensionPolicy is disabled by default:
  • Set enableLua in extensionApis to re-enable it. The disableLua field is deprecated. Any existing Lua-based EnvoyExtensionPolicy stops taking effect until Lua is explicitly enabled.
• Safe-upgrades ValidatingAdmissionPolicy moved into the chart templates:
  • If you install the Gateway API CRDs separately (for example with teg-crds-helm plus --skip-crds), add Helm ownership metadata — the meta.helm.sh/release-name and meta.helm.sh/release-namespace annotations and the app.kubernetes.io/managed-by=Helm label — to the existing ValidatingAdmissionPolicy/safe-upgrades.gateway.networking.k8s.io and its binding before upgrading, so Helm can adopt them.
  • If those resources are managed outside the chart (a cloud provider's managed Gateway API CRDs, for instance), note that --skip-crds does not skip chart-templated resources: disable them with crds.gatewayAPI.safeUpgradePolicy.enabled=false.
• FIPS images moved to a single registry:
  • FIPS deployments must update the Envoy proxy image override to fips-containers.teg.tetratelabs.com/envoy:distroless-v1.9.1. The former tetrate-envoy-gateway.containers.dl.tetrate.io/envoy location is no longer used for FIPS, and the tag now follows the TEG release version rather than the upstream Envoy version.
• Data-plane Envoy image tags follow the TEG version:
  • Automation that derives the Envoy image tag from the upstream Envoy version must be updated to use distroless-v1.9.0.
• clientIPDetection requires exactly one detection method:
  • An empty clientIPDetection: {} is now rejected by CEL validation. Specify exactly one of xForwardedFor, customHeader, or directSourceIP.
• mergeType restricted to xRoute targets:
  • SecurityPolicy and BackendTrafficPolicy objects that set mergeType while targeting a Gateway, a Gateway listener, a ListenerSet, or a ListenerSet listener are rejected. Remove mergeType from those policies before updating them after the CRD upgrade.
• Stricter apiKeyAuth.extractFrom validation:
  • The list must contain at least one entry, each entry must specify exactly one of headers, params, or cookies, and source names must be non-empty. Policies that previously applied with an empty or ambiguous extractFrom are now rejected.
• SDS reference secret URLs require the unix:// scheme:
  • Bare filesystem paths are rejected. Update any url value to, for example, unix:///var/run/secrets/workload-spiffe-uds/socket.
• Shared system CA SDS secret:
  • BackendTLSPolicy and Backend resources using WellKnownCACertificates: System now share one SDS secret named system_ca_certificates instead of one per resource. Brief traffic disruption is possible while the new secret warms. EnvoyPatchPolicy resources and extension servers referencing the old per-resource names must be updated; patching system_ca_certificates is not supported — use CACertificateRefs for a per-backend CA bundle. The PerResourceSystemCASecret runtime flag restores the old behavior.
• Tracing client sampling now defaults to 0%:
  • Client-forced tracing is no longer honored unless clientSamplingFraction is set explicitly. If you relied on clients forcing traces, set it before upgrading.
• EndpointSlice field indexing is on by default:
  • The EndpointSliceIndex runtime flag can increase controller memory usage on clusters with many EndpointSlices. Review the Envoy Gateway pod memory requests and limits, or opt out with runtimeFlags.disabled: [EndpointSliceIndex].
• xDS naming and layout changes affecting EnvoyPatchPolicy and extension servers:
  • JWT provider and requirement names are now content-derived rather than route-derived; EnvoyExtensionPolicy Lua source moved from per-route LuaPerRoute overrides to listener-level filters; shared-only global rate limit rules moved from route.rateLimits into typedPerFilterConfig; DNS clusters are generated with the envoy.cluster.dns cluster extension instead of dns_refresh_rate/respect_dns_ttl; and SDS clusters for Unix socket URLs carry a hash suffix. Audit every EnvoyPatchPolicy and extension server that matches on generated xDS names.
• ExternalName Services are rejected as route backends:
  • Previously they produced an invalid cluster that stalled configuration delivery for the whole snapshot. Replace ExternalName Services with a Backend resource.
• WebSocket backends forced to HTTP/1.1:
  • Services with appProtocol: kubernetes.io/ws or kubernetes.io/wss now use HTTP/1.1 upstream instead of negotiating HTTP/2.

---

Manual Migration Steps from 1.8 → v1.9.1

1. Update Gateway-API and Envoy Gateway CRDs

Pull the TEG v1.9.1 chart and apply the updated CRDs. Note that CRDs are packaged as a sub-chart under charts/gateway-helm/charts/crds.

helm pull oci://docker.io/tetrate/teg-envoy-gateway-helm --version v1.9.1 --untar

kubectl apply --force-conflicts --server-side \
-f ./teg-envoy-gateway-helm/charts/gateway-helm/crds/gatewayapi-crds.yaml

kubectl apply --force-conflicts --server-side \
-f ./teg-envoy-gateway-helm/charts/gateway-helm/crds/generated

2. Upgrade Tetrate Enterprise Gateway

For the community edition, no image overrides are needed:

helm upgrade teg \
oci://docker.io/tetrate/teg-envoy-gateway-helm \
--version v1.9.1 \
-n envoy-gateway-system

For the enterprise or enterprise FIPS editions, pass the values file that pins the edition's images — see TEG Editions and Install FIPS-validated TEG:

helm upgrade teg \
oci://docker.io/tetrate/teg-envoy-gateway-helm \
--version v1.9.1 \
--values values.yaml \
-n envoy-gateway-system

3. Post-Upgrade Validation

• Confirm the control plane is running the edition you expect, and — for the enterprise editions — that PHONE_HOME_ENABLED reflects your intent. See Confirm which edition is running.
• Verify the data-plane Envoy image is the version-tagged image (distroless-v1.9.0), and for FIPS deployments that it is pulled from fips-containers.teg.tetratelabs.com. Re-run the FIPS verification steps.
• If you previously overrode the Envoy image solely to enable the WAF, remove that override and confirm ExtendedSecurityPolicy still enforces as expected on the default image.
• Check that TCP and UDP routes are still programmed after the Gateway API v1.6 CRD upgrade — a missing CRD upgrade makes them silently disappear.
• Re-enable Lua explicitly (extensionApis.enableLua) if you use Lua EnvoyExtensionPolicy, and confirm the policies take effect.
• Audit EnvoyPatchPolicy resources and extension servers against the xDS naming changes (JWT providers, Lua filters, shared global rate limit rules, DNS clusters, SDS clusters, and the shared system_ca_certificates secret).
• Review Envoy Gateway controller memory usage after the EndpointSlice indexing change, especially on clusters with many EndpointSlices.
• Set clientSamplingFraction if you depend on client-forced tracing, which now defaults to 0%.
• Validate global rate limiting end to end. If you use the bundled Redis, confirm counters survive normal operation now that persistence is disabled; for production, migrate to your own Redis.
• Confirm SecurityPolicy and BackendTrafficPolicy objects no longer set mergeType on Gateway, listener, or ListenerSet targets, and that clientIPDetection specifies exactly one method.
• If you install the Gateway API CRDs separately, verify the safe-upgrades ValidatingAdmissionPolicy is either adopted by Helm or disabled with crds.gatewayAPI.safeUpgradePolicy.enabled=false.