Install on

Migration Matrix

Mon, 01 Jan 0001 00:00:00 +0000

Read the instructions below before making any changes to your cluster!

There are currently multiple paths for upgrading Emissary, depending on what version you’re currently running, what you want to be running, and whether you installed Emissary using Helm or YAML.

(To check out if you installed Emissary using Helm, run helm list --all-namespaces and see if Emissary is listed. If so, you installed using Helm.)

Read the instructions below before making any changes to your cluster!

If you installed Emissary using Helm

If you’re running.	You can upgrade to
Emissary 3.9	Emissary 3.10
Emissary 3.8.X	Emissary 3.10
Emissary 3.7.X	Emissary 3.10
Emissary 2.5	Emissary 3.10
Emissary 2.4.X	Emissary 2.5
Emissary 2.0.5	Emissary 2.5
Emissary 1.14	Emissary 2.5
Emissary prior to 1.14	Emissary 1.14

If you installed Emissary manually by applying YAML

If you’re running.	You can upgrade to
Emissary 3.9	Emissary 3.10
Emissary 3.8.X	Emissary 3.10
Emissary 3.7.X	Emissary 3.10
Emissary 2.5	Emissary 3.10
Emissary 2.4.X	Emissary 2.5
Emissary 2.0.5	Emissary 2.5
Emissary 1.14	Emissary 2.5
Emissary prior to 1.14	Emissary 1.14

Bare metal

Mon, 01 Jan 0001 00:00:00 +0000

In cloud environments, provisioning a readily available network load balancer with Emissary is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing Emissary.

Exposing Emissary via NodePort

The simplest way to expose an application in Kubernetes is via a NodePort service. In this configuration, we create the Emissary service] and identify type: NodePort instead of LoadBalancer. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to Emissary via the defined port.

Convert to v3alpha1

Mon, 01 Jan 0001 00:00:00 +0000

Once your Emissary 3.X installation is running, it is strongly recommended that you convert your existing configuration resources from getambassador.io/v2 to getambassador.io/v3alpha1.

While it is not necessary to convert all your resources to getambassador.io/v3alpha1 immediately, you should ultimately update them all for full functionality with Emissary

In general, the best way to convert any resource is to start with kubectl get: using kubectl get -o yaml on any getambassador.io/v2 resource will cause Emissary to translate it to a getambassador.io/v3alpha1 resource. You can then verify that the getambassador.io/v3alpha1 resource looks correct and re-apply it, which will convert the stored copy to getambassador.io/v3alpha1.

Integration to community projects

Mon, 01 Jan 0001 00:00:00 +0000

Ambassador Edge Stack is now available and includes additional functionality beyond the current Emissary. These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate limiting, a developer portal, and more.

Emissary integrations

If you still want to use just Emissary, don’t worry! Emissary is currently available out-of-the-box in some Kubernetes installers and local environments.

Migrate to Emissary 2.x

Mon, 01 Jan 0001 00:00:00 +0000

You can upgrade from any version of Ambassador Edge Stack or Emissary to any version of either by installing the new version in a new Kubernetes cluster, then copying over configuration as needed. This is the way to be absolutely certain that each installation cannot affect the other: it is extremely safe, but is also significantly more effort.

For example, to upgrade from some other version of Ambassador Edge Stack or Emissary to Emissary 2.X:

Migrate to Emissary 3.x

Mon, 01 Jan 0001 00:00:00 +0000

For example, to upgrade from some other version of Ambassador Edge Stack or Emissary to Emissary 3.X: