Helm

To migrate from Emissary 1.X to Emissary 2.X, see the Emissary migration matrix. This guide will not work for that, due to changes to the configuration resources used for Emissary 2.X.

Helm is a package manager for Kubernetes that automates the release and management of software on Kubernetes. Emissary can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading Emissary from an existing installation, or migrating from Emissary.

Before you begin

The Emissary Helm chart is hosted by Datawire and published at https://app.getambassador.io.

Start by adding this repo to your helm client with the following command:

helm repo add datawire https://app.getambassador.io
helm repo update

Install with Helm

When you run the Helm chart, it installs Emissary.

1. Install the Emissary CRDs.

   Before installing Emissary $version$ itself, you must configure your Kubernetes cluster to support the getambassador.io/v3alpha1 and getambassador.io/v2 configuration resources. This is required.

   kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml
   kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
   

   Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. If the emissary-apiext Deployment's Pods all stop running, you will not be able to use getambassador.io/v3alpha1 CRDs until restarting the emissary-apiext Deployment. There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl 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.

2. Install the Emissary Chart with the following command:

    helm install -n $productNamespace$ --create-namespace \
   	 $productHelmName$ datawire/$productHelmName$ && \
    kubectl rollout status  -n $productNamespace$ deployment/$productDeploymentName$ -w
   

3. Next Steps

   Emissary shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources.

   • The Listener Resource is required to configure which ports the Emissary pods listen on so that they can begin responding to requests.
   • The Mapping Resouce is used to configure routing requests to services in your cluster.
   • The Host Resource configures TLS termination for enablin HTTPS communication.
   • Explore how Emissary configures communication with clients

We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from Emissary to the demo service. Emissary $version$ includes a Deployment in the $productNamespace$ namespace called emissary-apiext. This is the APIserver extension that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. If the emissary-apiext Deployment's Pods all stop running, you will not be able to use getambassador.io/v3alpha1 CRDs until restarting the emissary-apiext Deployment.

For more advanced configuration and details about helm values, please see the helm chart.

Upgrading an existing installation

See the migration matrix for instructions about upgrading Emissary.