Upgrade Emissary-ingress 3.9.1 to Ambassador Edge Stack 3.12.1 (Helm)

You can upgrade from Emissary-ingress to Ambassador Edge Stack with a few simple commands. When you upgrade to Ambassador Edge Stack, you'll be able to access additional capabilities such as automatic HTTPS/TLS termination, Swagger/OpenAPI support, API catalog, Single Sign-On, and more.

Migration Overview

The recommended strategy for migration is to run Emissary-ingress 3.12.1 and Ambassador Edge Stack 3.12.1 side-by-side in the same cluster. This gives Ambassador Edge Stack 3.12.1 and Ambassador Edge Stack 3.12.1 access to all the same configuration resources, with some important notes:

1. If needed, you can use labels to further isolate configurations.

   If you need to prevent your Ambassador Edge Stack 3.12.1 installation from seeing a particular bit of Emissary-ingress 3.12.1 configuration, you can apply a Kubernetes label to the configuration resources that should be seen by your Ambassador Edge Stack 3.12.1 installation, then set its AMBASSADOR_LABEL_SELECTOR environment variable to restrict its configuration to only the labelled resources.

   For example, you could apply a version-two: true label to all resources that should be visible to Ambassador Edge Stack 3.12.1, then set AMBASSADOR_LABEL_SELECTOR=version-two=true in its Deployment.

2. Ambassador Edge Stack ACME and Filters will be disabled while Emissary-ingress is still running.

   Since Ambassador Edge Stack and Emissary-ingress share configuration, Ambassador Edge Stack cannot configure its ACME or other filter processors without also affecting Emissary-ingress. This migration process is written to simply disable these Ambassador Edge Stack features to make it simpler to roll back, if needed. Alternate, you can isolate the two configurations as described above.

3. Be careful to only have one Ambassador Edge Stack Agent running at a time.

   The Ambassador Edge Stack Agent is responsible for communications between Ambassador Edge Stack and Ambassador Cloud. If multiple versions of the Agent are running simultaneously, Ambassador Cloud could see conflicting information about your cluster.

   The best way to avoid multiple agents when installing with Helm is to use --set emissary-ingress.agent.enabled=false to tell Helm not to install a new Agent with Ambassador Edge Stack 3.12.1. Once testing is done, you can switch Agents safely.

4. Be careful about label selectors on Kubernetes Services!

   If you have services in Emissary-ingress 3.X that use selectors that will match Pods from Ambassador Edge Stack 3.12.1, traffic will be erroneously split between Emissary-ingress 3.X and Ambassador Edge Stack 3.12.1. The labels used by Ambassador Edge Stack 3.12.1 include:

You can also migrate by installing Ambassador Edge Stack 3.12.1 in a separate cluster. This permits absolute certainty that your Emissary-ingress 3.12.1 configuration will not be affected by changes meant for Ambassador Edge Stack 3.12.1, but it is more effort.

Side-by-Side Migration Steps

Migration is a six-step process:

1. Install new CRDs.

   Before installing Ambassador Edge Stack 3.12.1 itself, you need to update the CRDs in your cluster; Helm will not do this for you. This is mandatory during any upgrade of Ambassador Edge Stack.

   Ambassador Edge Stack 3.12.1 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 Ambassador Edge Stack 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 Ambassador Edge Stack/Emissary-ingress 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 Ambassador Edge Stack 3.12.1.

   Ambassador Edge Stack requires a valid license or cloud connect token to start. You can refer to the quickstart guide for instructions on how to obtain a free community license. Copy the cloud token command from the guide in Ambassador cloud for use below. If you already have a cloud connect token or a valid enterprise license, then you can skip this step.

   After installing the new CRDs, you need to install Ambassador Edge Stack 3.12.1 itself in the same namespace as your existing Emissary-ingress 3.12.1 installation. It's important to use the same namespace so that the two installations can see the same secrets, etc.

   Make sure that you set the various `create` flags when running Helm. This prevents Ambassador Edge Stack 3.12.1 from trying to configure filters that will adversely affect Emissary-ingress 3.12.1.

   Start by making sure that your datawire Helm repo is set correctly:

   Typically, Emissary-ingress 3.12.1 was installed in the emissary namespace. If you installed Emissary-ingress 3.12.1 in a different namespace, change the namespace in the commands below.

   • If you do not need to set AMBASSADOR_LABEL_SELECTOR:

   • If you do need to set AMBASSADOR_LABEL_SELECTOR, use --set, for example:

   You must use the edge-stack Helm chart to install Ambassador Edge Stack 3.12.1.

3. Test!

   Your Ambassador Edge Stack 3.12.1 installation should come up running with the configuration resources used by Emissary-ingress 3.12.1, including Listeners and Hosts.

   If you find that your Ambassador Edge Stack 3.12.1 installation and your Emissary-ingress 3.12.1 installation absolutely must have resources that are only seen by one version or the other way, see overview section 1, "If needed, you can use labels to further isolate configurations".

   If you find that you need to roll back, just reinstall your Emissary-ingress 3.12.1 CRDs and delete your installation of Ambassador Edge Stack 3.12.1.

4. When ready, switch over to Ambassador Edge Stack 3.12.1.

   You can run Emissary-ingress 3.12.1 and Ambassador Edge Stack 3.12.1 side-by-side as long as you care to. When you're ready to have Ambassador Edge Stack 3.12.1 handle traffic on its own, switch your original Emissary-ingress 3.12.1 Service to point to Ambassador Edge Stack 3.12.1. Use kubectl edit -n emissary service emissary-ingress and change the selectors to:

   Repeat using kubectl edit service ambassador-admin for the ambassador-admin Service.

5. Create an Ambassador Cloud Connect Token

   Ambassador Edge Stack requires a license to operate. Licenses are obtained and refreshed automatically using an API Token. If your installation of Ambassador Edge Stack is already connected to the cloud then you can skip this step. Otherwise, you can create a Cloud Connect Token in Ambassador Cloud and apply it using the Helm upgrade command below. For more information on licensing please refer to the license page.

6. Install the Ambassador Edge Stack 3.12.1 Ambassador Agent.

   First, scale the Emissary-ingress agent to 0:

   Once that's done, install the new Agent:

7. Finally, enable ACME and filtering in Ambassador Edge Stack 3.12.1.

   First, scale the Emissary-ingress Deployment to 0:

   Once that's done, enable ACME and filtering in Ambassador Edge Stack 3.12.1:

Congratulations! At this point, Ambassador Edge Stack 3.12.1 is fully running, and it's safe to remove the old emissary and emissary-agent Deployments:

You may also want to redirect DNS to the edge-stack Service and remove the ambassador Service.