Since Emissary-ingress's configuration is entirely stored in Kubernetes resources, upgrading between versions is straightforward.
Emissary-ingress 3 is functionally compatible with Emissary-ingress 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.
Emissary-ingress 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all
LogServices must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed.
You can refer to the Major changes in Emissary-ingress 3.x guide for an overview of the changes.
Emissary-ingress 3.2 fixed a bug with
Listener.spec.selectornot being properly enforced. In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating
Mappings, if the
hostnamethat matched the
Hostthen they would be associated regardless of the configuration of the
Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels.
The environment variable
DISABLE_STRICT_LABEL_SELECTORScan be set to
"true"on the Emissary-ingress deployment to revert to the old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet.
For more information on
DISABLE_STRICT_LABEL_SELECTORSsee the Environment Variables page.
Check Transport Protocol usage on all resources before migrating.
LogServicesthat use the
grpcprotocol will now need to explicilty set
protocol_version: "v3". If not set or set to
v2then an error will be posted and a static response will be returned.
protocol_versionshould be updated to
v3for all of the above resources while still running Emissary-ingress 2.5.1. As of version
2.3.z+, support for
v3is supported in order to allow migration from
v3before upgrading to Emissary-ingress 3.9.1 where support for
Upgrading any application code for your own implementations of these services is very straightforward.
The following imports simply need to be updated to switch from Envoy's Transport Protocol
v3, and then the configuration for these resources can be updated to add the
protocl_version: "v3"when the updated service is deployed.
Check removed runtime changes
Support for LightStep tracing driver removed
Emissary-ingress 3.4 is based on Envoy 1.24.1 which removed support for the
LightStep tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.
Migration is a two-step process:
Install new CRDs.
After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions in previous version of Emissary-ingress and does not require the complex migration steps that the migration from 1.x tto 2.x required.
Before installing Emissary-ingress 3.9.1 itself, you need to update the CRDs in your cluster. This is mandatory during any upgrade of Emissary-ingress.
Install Emissary-ingress 3.9.1.
After installing the new CRDs, upgrade Emissary-ingress 3.9.1.