Upgrade Emissary-ingress 2.3.Z to Emissary-ingress 3.1.0 (YAML)

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.

Resources to check before migrating to 3.1.0.

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 AuthService, RatelimitService, and 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.

1. Check Transport Protocol usage on all resources before migrating.

   The AuthService, RatelimitService, and LogServices that use the grpc protocol will now need to explicilty set protocol_version: "v3". If not set or set to v2 then an error will be posted and a static response will be returned.

   protocol_version should be updated to v3 for all of the above resources while still running Emissary-ingress 2.3.2. As of version 2.3.z+, support for protocol_version v2 and v3 is supported in order to allow migration from protocol_version v2 to v3 before upgrading to Emissary-ingress 3.1.0 where support for v2 is removed.

   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 v2 to v3, and then the configuration for these resources can be updated to add the protocl_version: "v3" when the updated service is deployed.

   v2 Imports:

   v3 Imports:

2. Check removed runtime changes

3. 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.1.0 itself, you need to update the CRDs in your cluster. This is mandatory during any upgrade of Emissary-ingress.

   Emissary-ingress 3.1.0 includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension that supports converting Emissary-ingress CRDs between getambassador.io/v2and getambassador.io/v3alpha1. This Deployment needs to be running at all times.
   If the emissary-apiext Deployment's Pods all stop running, you will not be able to use getambassador.io/v3alpha1 CRDs until restarting the emissary-apiext Deployment.
   There is a known issue with the emissary-apiext service that impacts all Emissary-ingress 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running Emissary-ingress/Ambassador Edge Stack 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system. This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.

4. Install Emissary-ingress 3.1.0.

   After installing the new CRDs, upgrade Emissary-ingress 3.1.0.

   Our emissary-emissaryns.yaml file uses the `emissary` namespace, since this is the default for Emissary-ingress. We also publish emissary-defaultns.yaml for the `default` namespace. For any other namespace, you should download one of these files and edit the namespaces manually.