Major Changes in Emissary 3.X

The 3.X family introduces a number of changes to ensure Emissary keeps up with latest Envoy versions and to support new features such as HTTP/3. We welcome feedback! Join us on Slack and let us know what you think.

Emissary 3 is functionally compatible with Emissary 2.x, but with any major upgrade there are some changes to consider. Such as, Envoy removing support for V2 Transport Protocol features. Below we will outline some of these changes and things to consider when upgrading.

1. Envoy Upgraded to 1.22

Emissary 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which keeps Emissary up-to-date with the latest security fixes, bug fixes, performance improvements and feature enhancements provided by Envoy Proxy. Most of the changes are under the hood but the most notable change to developers is the removal of support for Envoy V2 Transport Protocol. This means all AuthServices and LogServices must be updated to use the V3 Protocol.

This also means some of the v2 runtime bootstrap flags have been removed as well:

# No longer necessary because this was removed from Envoy
# Emissary already was converted to use the compressor API
# https://www.envoyproxy.io/docs/envoy/v1.22.0/configuration/http/http_filters/compressor_filter#config-http-filters-compressor
"envoy.deprecated_features.allow_deprecated_gzip_http_filter": true,

# Upgraded to v3, all support for V2 Transport Protocol removed
"envoy.deprecated_features:envoy.api.v2.route.HeaderMatcher.regex_match": true,
"envoy.deprecated_features:envoy.api.v2.route.RouteMatch.regex": true,

# Developer will need to upgrade TracingService to V3 protocol which no longer supports HTTP_JSON_V1
"envoy.deprecated_features:envoy.config.trace.v2.ZipkinConfig.HTTP_JSON_V1": true,

# V2 protocol removed so flag no longer necessary
"envoy.reloadable_features.enable_deprecated_v2_api": true,
Learn more about Envoy Proxy changes.

2. Envoy V2 Protocol Support Removed

With the upgrade to Envoy 1.22, the V2 Envoy Transport Protocol is no longer supported. Emissary 3.X only supports V3 Envoy API.

The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect of changing the transport protocol. The setting of transport_protocol to v2 is no longer supported within CRDS (AuthService, etc...). An error will now be logged and Emissary will not configure envoy correctly. You should remove this field from your CRD's or convert it to v3 the only supported version at this time.