import Alert from '@material-ui/lab/Alert';
This guide covers migrating from $productName$ 2.4 to $productName$ $versionTwoX$. If this is not your exact situation, see the migration matrix. This guide is written for upgrading an installation made using Helm. If you did not originally install with Helm, see the YAML-based upgrade instructions.Since
Migration is a two-step process:
-
Install new CRDs.
Before installing
$productName$ $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$productName$ .kubectl apply -f https://app.getambassador.io/yaml/edge-stack/$versionTwoX$/aes-crds.yaml kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
$productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace calledemissary-apiext
. This is the APIserver extension that supports converting$productName$ CRDs betweengetambassador.io/v2
andgetambassador.io/v3alpha1
. This Deployment needs to be running at all times. If theemissary-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 theemissary-apiext
service that impacts all$productName$ 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$productName$ /$OSSproductName$ 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
$productName$ $versionTwoX$ .After installing the new CRDs, use Helm to install
$productName$ $versionTwoX$ . Start by making sure that yourdatawire
Helm repo is set correctly:helm repo remove datawire helm repo add datawire https://app.getambassador.io helm repo update
Then, update your
$productName$ 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.You must use thehelm upgrade -n $productNamespace$ \ $productHelmName$ datawire/$productHelmName$ && \ kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w
$productHelmName$
Helm chart to install$productName$ 2.X. Do not use theambassador
Helm chart.