Install with Helm

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

Before you begin

The Emissary-ingress 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:

Install with Helm

When you run the Helm chart, it installs Emissary-ingress.

1. Install the Emissary-ingress CRDs.

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

   Emissary-ingress 2.2.2 includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension that supports converting Emissary-ingress CRDs between getambassador.io/v2and 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-ingress 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-ingress/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-ingress Chart with the following command:

3. Next Steps

   Emissary-ingress 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-ingress 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-ingress 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-ingress to the demo service.
   Emissary-ingress 2.2.2 includes a Deployment in the emissary namespace called emissary-apiext. This is the APIserver extension that supports converting Emissary-ingress CRDs between getambassador.io/v2and 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-ingress.