Upgrade Ambassador Edge Stack 1.14.X to Ambassador Edge Stack 2.5.1 (Helm)

We're pleased to introduce Ambassador Edge Stack 2.5.1! The 2.X family introduces a number of changes to allow Ambassador Edge Stack to more gracefully handle larger installations (including multitenant or multiorganizational installations), reduce memory footprint, and improve performance. In keeping with SemVer, Ambassador Edge Stack 2.X introduces some changes that aren't backward-compatible with 1.X. These changes are detailed in Major Changes in Ambassador Edge Stack 2.X.

Migration Overview

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

1. Ambassador Edge Stack 1.14 will not see any getambassador.io/v3alpha1 resources.

   This is intentional; it provides a way to apply configuration only to Ambassador Edge Stack 2.5.1, while not interfering with the operation of your Ambassador Edge Stack 1.14 installation.

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

   If you need to prevent your Ambassador Edge Stack 2.5.1 installation from seeing a particular bit of Ambassador Edge Stack 1.14 configuration, you can apply a Kubernetes label to the configuration resources that should be seen by your Ambassador Edge Stack 2.5.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 2.5.1, then set AMBASSADOR_LABEL_SELECTOR=version-two=true in its Deployment.

3. Ambassador Edge Stack 1.14 must remain in control of ACME while both installations are running.

   The processes that handle ACME challenges cannot be managed by both Ambassador Edge Stack 1.X and Ambassador Edge Stack 2.5.1 at the same time. The instructions below disable ACME in Ambassador Edge Stack 2.5.1, allowing Ambassador Edge Stack 1.14 to continue managing it.

   This implies that any new Hosts used for Ambassador Edge Stack 1.14 should be created using getambassador.io/v2 so that Ambassador Edge Stack 1.14 can see them.

4. Check AuthService and RateLimitService resources, if any.

   If you have an AuthService or RateLimitService installed, make sure that they are using the namespace-qualified DNS name. If they are not, the initial migration tests may fail.

   Additionally, when installing with Helm, you must make sure that Ambassador Edge Stack 2.5.1 does not attempt to create duplicate AuthService and RateLimitService entries. Add

   and

   on the Helm command line to prevent duplicating these resources.

5. 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 2.5.1. Once testing is done, you can switch Agents safely.

6. If you use ACME for multiple Hosts, add a wildcard Host too.

   This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release.

7. Be careful about label selectors on Kubernetes Services!

   If you have services in Ambassador Edge Stack 1.14 that use selectors that will match Pods from Ambassador Edge Stack 2.5.1, traffic will be erroneously split between Ambassador Edge Stack 1.14 and Ambassador Edge Stack 2.5.1. The labels used by Ambassador Edge Stack 2.5.1 include:

You can also migrate by installing Ambassador Edge Stack 2.5.1 in a separate cluster. This permits absolute certainty that your Ambassador Edge Stack 1.14 configuration will not be affected by changes meant for Ambassador Edge Stack 2.5.1, and it eliminates concerns about ACME, but it is more effort.

Side-by-Side Migration Steps

Migration is an eight-step process:

1. Make sure that older configuration resources are not present.

   Ambassador Edge Stack 2.X does not support getambassador.io/v0 or getambassador.io/v1 resources, and Kubernetes will not permit removing support for CRD versions that are still in use for stored resources. To verify that no resources older than getambassador.io/v2 are active, run

   If v1 is present in the output, do not begin migration. The old resources must be converted to getambassador.io/v2 and the storedVersion information in the cluster must be updated. If necessary, contact Ambassador Labs on Slack for more information.

2. Install new CRDs.

   Before installing Ambassador Edge Stack 2.5.1 itself, you must configure your Kubernetes cluster to support its new getambassador.io/v3alpha1 configuration resources. Note that getambassador.io/v2 resources are still supported, but you must install support for getambassador.io/v3alpha1 to run Ambassador Edge Stack 2.5.1, even if you intend to continue using only getambassador.io/v2 resources for some time.

   Ambassador Edge Stack 2.5.1 includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension that supports converting Ambassador Edge Stack 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.

3. Install Ambassador Edge Stack 2.5.1.

   After installing the new CRDs, you need to install Ambassador Edge Stack 2.5.1 itself in the same namespace as your existing Ambassador Edge Stack 1.14 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 AES_ACME_LEADER_DISABLE flag. This prevents Ambassador Edge Stack 2.5.1 from trying to manage ACME, so that Ambassador Edge Stack 1.14 can do it instead.

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

   Typically, Ambassador Edge Stack 1.14 was installed in the ambassador namespace. If you installed Ambassador Edge Stack 1.14 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 for Ambassador Edge Stack 2.5.1. Do not use the ambassador Helm chart.

4. Install Listeners and Hosts as needed.

   An important difference between Ambassador Edge Stack 1.14 and Ambassador Edge Stack 2.5.1 is the new mandatory Listener CRD. Also, when running both installations side by side, you will need to make sure that a Host is present for the new Ambassador Edge Stack 2.5.1 Service. For example:

   Make sure that any Hosts you create use API version getambassador.io/v2, so that they can be managed by Ambassador Edge Stack 1.14 as long as both installations are running.

   This example requires that you know the hostname for the Ambassador Edge Stack Service ($EMISSARY_HOSTNAME) and that you have created a TLS Secret for it in $EMISSARY_TLS_SECRET.

5. Test!

   Your Ambassador Edge Stack 2.5.1 installation can support the getambassador.io/v2 configuration resources used by Ambassador Edge Stack 1.14, but you may need to make some changes to the configuration, as detailed in the documentation on configuring Ambassador Edge Stack Communications and updating CRDs to getambassador.io/v3alpha1.

   Kubernetes will not allow you to have a getambassador.io/v3alpha1 resource with the same name as a getambassador.io/v2 resource or vice versa: only one version can be stored at a time.
   
   If you find that your Ambassador Edge Stack 2.5.1 installation and your Ambassador Edge Stack 1.14 installation absolutely must have resources that are only seen by one version or the other way, see overview section 2, "If needed, you can use labels to further isolate configurations".

   If you find that you need to roll back, just reinstall your 1.14 CRDs, delete your installation of Ambassador Edge Stack 2.5.1, and delete the emissary-system namespace.

6. When ready, switch over to Ambassador Edge Stack 2.5.1.

   You can run Ambassador Edge Stack 1.14 and Ambassador Edge Stack 2.5.1 side-by-side as long as you care to. However, taking full advantage of Ambassador Edge Stack 2.X's capabilities requires updating your configuration to use getambassador.io/v3alpha1 configuration resources, since some useful features in Ambassador Edge Stack 2.5.1 are only available using getambassador.io/v3alpha1 resources.

   When you're ready to have Ambassador Edge Stack 2.5.1 handle traffic on its own, switch your original Ambassador Edge Stack 1.14 Service to point to Ambassador Edge Stack 2.5.1. Use kubectl edit service ambassador and change the selectors to:

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

7. Install the Ambassador Edge Stack 2.5.1 Ambassador Agent.

   First, scale the 1.14 agent to 0:

   Once that's done, install the new Agent. Note that if you needed to set AMBASSADOR_LABEL_SELECTOR, you must add that to this helm upgrade command.

8. Finally, enable ACME in Ambassador Edge Stack 2.5.1.

   First, scale the 1.14 Ambassador to 0:

   Once that's done, enable ACME in Ambassador Edge Stack 2.5.1. Note that if you needed to set AMBASSADOR_LABEL_SELECTOR, you must add that to this helm upgrade command.

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

Once Ambassador Edge Stack 1.14 is no longer running, you may convert any remaining getambassador.io/v2 resources to getambassador.io/v3alpha1. You may also want to redirect DNS to the edge-stack Service and remove the ambassador Service.