This guide covers migrating from Ambassador Edge Stack 3.9.Z to Ambassador Edge Stack 3.12.1. If this is not your exact situation, see the migration matrix.
This guide is written for upgrading an installation made without using Helm. If you originally installed with Helm, see the Helm-based upgrade instructions.
Since Ambassador Edge Stack's configuration is entirely stored in Kubernetes resources, upgrading between
versions is straightforward.
Migration Steps
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 Ambassador Edge Stack and does not require the complex migration steps that the migration from 1.x tto 2.x required.
Before installing Ambassador Edge Stack 3.12.1 itself, you need to update the CRDs in
your cluster. 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 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.
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 command below.
For more information on licensing please refer to the license page.
Install Ambassador Edge Stack 3.12.1.
After installing the new CRDs, upgrade Ambassador Edge Stack 3.12.1:
Edge Stack