DocsEmissary-ingressUpgrade Emissary-ingress 1.14.X (Helm)
Upgrade Emissary-ingress 1.14.X (Helm)
We're pleased to introduce Emissary-ingress 2.5.1! The 2.X family introduces a number of changes to allow Emissary-ingress to more gracefully handle larger installations (including multitenant or multiorganizational installations), reduce memory footprint, and improve performance. In keeping with SemVer, Emissary-ingress 2.X introduces some changes that aren't backward-compatible with 1.X. These changes are detailed in Major Changes in Emissary-ingress 2.X.
The recommended strategy for migration is to run Emissary-ingress 1.14 and Emissary-ingress 2.5.1 side-by-side in the same cluster. This gives Emissary-ingress 2.5.1 and Emissary-ingress 1.14 access to all the same configuration resources, with some important caveats:
Emissary-ingress 1.14 will not see any
This is intentional; it provides a way to apply configuration only to Emissary-ingress 2.5.1, while not interfering with the operation of your Emissary-ingress 1.14 installation.
If needed, you can use labels to further isolate configurations.
If you need to prevent your Emissary-ingress 2.5.1 installation from seeing a particular bit of Emissary-ingress 1.14 configuration, you can apply a Kubernetes label to the configuration resources that should be seen by your Emissary-ingress 2.5.1 installation, then set its
AMBASSADOR_LABEL_SELECTORenvironment variable to restrict its configuration to only the labelled resources.
For example, you could apply a
version-two: truelabel to all resources that should be visible to Emissary-ingress 2.5.1, then set
AMBASSADOR_LABEL_SELECTOR=version-two=truein its Deployment.
Be careful about label selectors on Kubernetes Services!
If you have services in Emissary-ingress 1.14 that use selectors that will match Pods from Emissary-ingress 2.5.1, traffic will be erroneously split between Emissary-ingress 1.14 and Emissary-ingress 2.5.1. The labels used by Emissary-ingress 2.5.1 include:
Be careful to only have one Emissary-ingress Agent running at a time.
The Emissary-ingress Agent is responsible for communications between Emissary-ingress 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 agent.enabled=falseto tell Helm not to install a new Agent with Emissary-ingress 2.5.1. Once testing is done, you can switch Agents safely.
You can also migrate by installing Emissary-ingress 2.5.1 in a separate cluster. This permits absolute certainty that your Emissary-ingress 1.14 configuration will not be affected by changes meant for Emissary-ingress 2.5.1, and it eliminates concerns about ACME, but it is more effort.
Side-by-Side Migration Steps
Migration is a seven-step process:
Make sure that older configuration resources are not present.
Emissary-ingress 2.X does not support
getambassador.io/v1resources, 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/v2are active, run
v1is present in the output, do not begin migration. The old resources must be converted to
storedVersioninformation in the cluster must be updated. If necessary, contact Ambassador Labs on Slack for more information.
Install new CRDs.
Before installing Emissary-ingress 2.5.1 itself, you must configure your Kubernetes cluster to support its new
getambassador.io/v3alpha1configuration resources. Note that
getambassador.io/v2resources are still supported, but you must install support for
getambassador.io/v3alpha1to run Emissary-ingress 2.5.1, even if you intend to continue using only
getambassador.io/v2resources for some time.
Install Emissary-ingress 2.5.1.
After installing the new CRDs, you need to install Emissary-ingress 2.5.1 itself in the same namespace as your existing Emissary-ingress 1.14 installation. It's important to use the same namespace so that the two installations can see the same secrets, etc.
Start by making sure that your
emissaryHelm repo is set correctly:
Typically, Emissary-ingress 1.14 was installed in the
ambassadornamespace. If you installed Emissary-ingress 1.14 in a different namespace, change the namespace in the commands below.
If you do not need to set
If you do need to set
--set, for example:
Hosts as needed.
An important difference between Emissary-ingress 1.14 and Emissary-ingress 2.5.1 is the new mandatory
ListenerCRD. Also, when running both installations side by side, you will need to make sure that a
Hostis present for the new Emissary-ingress 2.5.1 Service. For example:
This example requires that you know the hostname for the Emissary-ingress Service (
$EMISSARY_HOSTNAME) and that you have created a TLS Secret for it in
Your Emissary-ingress 2.5.1 installation can support the
getambassador.io/v2configuration resources used by Emissary-ingress 1.14, but you may need to make some changes to the configuration, as detailed in the documentation on configuring Emissary-ingress Communications and updating CRDs to
If you find that you need to roll back, just reinstall your 1.14 CRDs and delete your installation of Emissary-ingress 2.5.1.
When ready, switch over to Emissary-ingress 2.5.1.
You can run Emissary-ingress 1.14 and Emissary-ingress 2.5.1 side-by-side as long as you care to. However, taking full advantage of Emissary-ingress 2.X's capabilities requires updating your configuration to use
getambassador.io/v3alpha1configuration resources, since some useful features in Emissary-ingress 2.5.1 are only available using
When you're ready to have Emissary-ingress 2.5.1 handle traffic on its own, switch your original Emissary-ingress 1.14 Service to point to Emissary-ingress 2.5.1. Use
kubectl edit service ambassadorand change the
kubectl edit service ambassador-adminfor the
Finally, install the Emissary-ingress 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
Congratulations! At this point, Emissary-ingress 2.5.1 is fully running and it's safe to remove the
Once Emissary-ingress 1.14 is no longer running, you may convert
getambassador.io/v2 resources to
You may also want to redirect DNS to the
edge-stack Service and remove the
ON THIS PAGE