3.4.x to latest 3.x

Since Emissary’s configuration is entirely stored in Kubernetes resources, upgrading between versions is straightforward.

Resources to check before migrating to $version$.

Emissary 3.4 has been upgraded from Envoy 1.23 to 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 Steps

Migration is a two-step process:

1. Install new CRDs.

   Before installing Emissary $version$ itself, you need to update the CRDs in your cluster. This is mandatory during any upgrade of Emissary.

   kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml
   kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
   

   Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension that supports converting Emissary CRDs between getambassador.io/v2 and 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 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/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.

2. Install Emissary $version$.

   After installing the new CRDs, upgrade Emissary $version$.

   Our emissary-emissaryns.yaml file uses the `emissary` namespace, since this is the default for Emissary. 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.

   kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \
   kubectl rollout status  -n emissary deployment/emissary-ingress -w