You can upgrade from Emissary-ingress to Ambassador Edge Stack with a few simple commands. When you upgrade to Ambassador Edge Stack, you'll be able to access additional capabilities such as automatic HTTPS/TLS termination, Swagger/OpenAPI support, API catalog, Single Sign-On, and more. For more about the differences between Ambassador Edge Stack and Emissary-ingress, see the Editions page.
The recommended strategy for migration is to run Emissary-ingress 2.3.1 and Ambassador Edge Stack 2.3.1 side-by-side in the same cluster. This gives Ambassador Edge Stack 2.3.1 and Ambassador Edge Stack 2.3.1 access to all the same configuration resources, with some important notes:
If needed, you can use labels to further isolate configurations.
If you need to prevent your Ambassador Edge Stack 2.3.1 installation from seeing a particular bit of Emissary-ingress 2.3.1 configuration, you can apply a Kubernetes label to the configuration resources that should be seen by your Ambassador Edge Stack 2.3.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.3.1, then set
AMBASSADOR_LABEL_SELECTOR=version-two=truein its Deployment.
Ambassador Edge Stack ACME and
Filters will be disabled while Emissary-ingress is still running.
Since Ambassador Edge Stack and Emissary-ingress share configuration, Ambassador Edge Stack cannot configure its ACME or other filter processors without also affecting Emissary-ingress. This migration process is written to simply disable these Ambassador Edge Stack features to make it simpler to roll back, if needed. Alternate, you can isolate the two configurations as described above.
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.3.1. Once testing is done, you can switch Agents safely.
Be careful about label selectors on Kubernetes Services!
If you have services in Emissary-ingress 2.3 that use selectors that will match Pods from Ambassador Edge Stack 2.3.1, traffic will be erroneously split between Emissary-ingress 2.3 and Ambassador Edge Stack 2.3.1. The labels used by Ambassador Edge Stack 2.3.1 include:yamlapp.kubernetes.io/name: edge-stackapp.kubernetes.io/instance: edge-stackapp.kubernetes.io/part-of: edge-stackapp.kubernetes.io/managed-by: getambassador.ioproduct: aesprofile: main
You can also migrate by installing Ambassador Edge Stack 2.3.1 in a separate cluster. This permits absolute certainty that your Emissary-ingress 2.3.1 configuration will not be affected by changes meant for Ambassador Edge Stack 2.3.1, but it is more effort.
Migration is a six-step process:
Install new CRDs.
Before installing Ambassador Edge Stack 2.3.1 itself, you need to update the CRDs in your cluster. This is mandatory during any upgrade of Ambassador Edge Stack.shellkubectl apply -f https://app.getambassador.io/yaml/edge-stack/2.3.1/aes-crds.yaml && \kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
Install Ambassador Edge Stack 2.3.1.
After installing the new CRDs, you need to install Ambassador Edge Stack 2.3.1 itself in the same namespace as your existing Emissary-ingress 2.3.1 installation. It's important to use the same namespace so that the two installations can see the same secrets, etc.
We publish three manifests for different namespaces. Use only the one that matches the namespace into which you installed Emissary-ingress 2.3.1:
All three files are set up as follows:
- They set the
AES_ACME_LEADER_DISABLEenvironment variable; you'll enable ACME towards the end of the migration.
- They do NOT create any
RateLimitService, since your Emissary-ingress may have these defined. Again, you'll manage these at the end of migration.
- They do NOT set
- They do NOT install the Ambassador Agent, since there is already an Ambassador Agent running for Emissary-ingress 2.3.1.
If any of these do not match your situation, download
aes-emissaryns-migration.yamland edit it as needed.
Assuming you're using the
emissarynamespace, as was typical for Emissary-ingress 2.3.1:
If you need to set
aes-emissaryns-migration.yamland edit it to do so.shellkubectl apply -f https://app.getambassador.io/yaml/edge-stack/2.3.1/aes-emissaryns-migration.yaml && \kubectl rollout status -n emissary deployment/aes -w
Your Ambassador Edge Stack 2.3.1 installation should come up running with the configuration resources used by Emissary-ingress 2.3.1, including
If you find that you need to roll back, just reinstall your Emissary-ingress 2.3.1 CRDs and delete your installation of Ambassador Edge Stack 2.3.1.
When ready, switch over to Ambassador Edge Stack 2.3.1.
You can run Emissary-ingress 2.3.1 and Ambassador Edge Stack 2.3.1 side-by-side as long as you care to. When you're ready to have Ambassador Edge Stack 2.3.1 handle traffic on its own, switch your original Emissary-ingress 2.3.1 Service to point to Ambassador Edge Stack 2.3.1. Use
kubectl edit -n emissary service emissary-ingressand change the
selectorsto:yamlapp.kubernetes.io/instance: edge-stackapp.kubernetes.io/name: edge-stackprofile: main
kubectl edit service ambassador-adminfor the
Install the Ambassador Edge Stack 2.3.1 Ambassador Agent.
First, scale the Emissary-ingress agent to 0:shellkubectl scale -n emissary deployment/emissary-ingress-agent --replicas=0
Once that's done, install the new Agent:shellkubectl apply -f https://app.getambassador.io/yaml/edge-stack/2.3.1/aes-emissaryns-agent.yaml && \kubectl rollout status -n emissary deployment/edge-stack-agent -w
Finally, enable ACME and filtering in Ambassador Edge Stack 2.3.1.
First, make sure that no
RateLimitServiceresources are present; delete these if necessary.
If you are currently using an external authentication service that provides functionality you'll still require, turn it into an
FilterPolicyto direct requests that need it correctly).
If you are currently using a
RateLimitService, you can set up Edge Stack Rate Limiting instead.
After making sure no
RateLimitServiceresources are present, scale the Emissary-ingress Deployment to 0:bashkubectl scale -n emissary deployment/emissary-ingress --replicase=0
Once that's done, apply resources specific to Ambassador Edge Stack:bashkubectl apply -f https://app.getambassador.io/yaml/edge-stack/2.3.1/resources-migration.yaml
Then, finally, enable ACME and filtering in Ambassador Edge Stack 2.3.1:bashkubectl set env -n emissary deployment/aes AES_ACME_LEADER_DISABLE-kubectl rollout status -n emissary deployment/aes -w
Congratulations! At this point, Ambassador Edge Stack 2.3.1 is fully running, and
it's safe to remove the old
kubectl delete -n emissary deployment/emissary deployment/emissary-agent
You may also want to redirect DNS to the
edge-stack Service and remove the