YAML

In this guide, we’ll walk you through installing Emissary in your Kubernetes cluster.

The manual install process does not allow for as much control over configuration as the Helm install method, so if you need more control over your Emissary installation, it is recommended that you use helm.

Before you begin

Emissary is designed to run in Kubernetes for production. The most essential requirements are:

• Kubernetes 1.11 or later
• The kubectl command-line tool

Install with YAML

Emissary is typically deployed to Kubernetes from the command line. If you don’t have Kubernetes, you should use our Docker image to deploy Emissary locally.

1. In your terminal, run the following command:

   kubectl create namespace $productNamespace$ || true
   kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \
   kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \
   kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$
   

   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. 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. Determine the IP address or hostname of your cluster by running the following command:

   kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}"
   

   Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address.

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

Upgrading an existing installation

See the migration matrix for instructions about upgrading Emissary.