2.0.x to latest 2.x
Since Emissary’s configuration is entirely stored in Kubernetes resources, upgrading between minor versions is straightforward.
Migration is a two-step process:
-
Install new CRDs.
Before installing Emissary $versionTwoX$ itself, you need to update the CRDs in your cluster; Helm will not do this for you. This is mandatory during any upgrade of Emissary.
kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
Emissary $versionTwoX$ includes a Deployment in the `emissary-system` namespace called emissary-apiext
. This is the APIserver extension that supports converting Emissary CRDs betweengetambassador.io/v2
andgetambassador.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 usegetambassador.io/v3alpha1
CRDs until restarting theemissary-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 runningkubectl delete --all secrets --namespace=emissary-system
to delete the existing certificate, and then restart theemissary-apiext
deployment withkubectl 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. -
Install Emissary $versionTwoX$.
After installing the new CRDs, use Helm to install Emissary $versionTwoX$. Start by making sure that your
datawire
Helm repo is set correctly:helm repo remove datawire helm repo add datawire https://app.getambassador.io helm repo update
Then, update your Emissary installation in the
$productNamespace$
namespace. If necessary for your installation (e.g. if you were running withAMBASSADOR_SINGLE_NAMESPACE
set), you can choose a different namespace.helm upgrade -n $productNamespace$ \ $productHelmName$ datawire/$productHelmName$ && \ kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w
You must use the $productHelmName$
Helm chart for Emissary 2.X. Do not use theambassador
Helm chart.