DocsEdge StackUpgrade Ambassador Edge Stack 1.14.X to Ambassador Edge Stack 2.5.1 (Helm)
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.
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:
Ambassador Edge Stack 1.14 will not see any
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.
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_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 Ambassador Edge Stack 2.5.1, then set
AMBASSADOR_LABEL_SELECTOR=version-two=truein its Deployment.
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/v2so that Ambassador Edge Stack 1.14 can see them.
RateLimitServiceresources, if any.
If you have an
RateLimitServiceinstalled, 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
on the Helm command line to prevent duplicating these resources.
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=falseto tell Helm not to install a new Agent with Ambassador Edge Stack 2.5.1. Once testing is done, you can switch Agents safely.
If you use ACME for multiple
Hosts, add a wildcard
This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release.
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:
Make sure that older configuration resources are not present.
Ambassador Edge Stack 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 Ambassador Edge Stack 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 Ambassador Edge Stack 2.5.1, even if you intend to continue using only
getambassador.io/v2resources for some time.
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.
Start by making sure that your
datawireHelm repo is set correctly:
Typically, Ambassador Edge Stack 1.14 was installed in the
ambassadornamespace. 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
If you do need to set
--set, for example:
Hosts as needed.
An important difference between Ambassador Edge Stack 1.14 and Ambassador Edge Stack 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 Ambassador Edge Stack 2.5.1 Service. For example:
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
Your Ambassador Edge Stack 2.5.1 installation can support the
getambassador.io/v2configuration 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
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
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/v3alpha1configuration resources, since some useful features in Ambassador Edge Stack 2.5.1 are only available using
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 ambassadorand change the
kubectl edit service ambassador-adminfor the
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
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
Congratulations! At this point, Ambassador Edge Stack 2.5.1 is fully running, and
it's safe to remove the old
Once Ambassador Edge Stack 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