Install Emissary

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

If you still want to use just Emissary, don’t worry! You can follow the directions below to install it. Throughout the documentation, you’ll see product tags at the top of the page, so you know what features apply to Emissary.

Install Emissary

• Kubernetes YAML
• Helm
• Kubernetes distributions

Kubernetes YAML

In this tutorial, we’ll walk through the process of deploying Emissary in Kubernetes for ingress routing. Emissary provides all the functionality of a traditional ingress controller (i.e., path-based routing) while exposing many additional capabilities such as authentication, URL rewriting, CORS, rate limiting, and automatic metrics collection (the mappings reference contains a full list of supported options). Note that Ambassador Edge Stack can be used as an Ingress Controller.

For more background on Kubernetes ingress, read this blog post.

Emissary is designed to allow service authors to control how their service is published to the Internet. We accomplish this by permitting a wide range of annotations on the service, which Emissary reads to configure its Envoy Proxy.

Below, we’ll configure Emissary to map /httpbin/ to httpbin.org.

1. Deploying Emissary

The following steps deploy Emissary in the default namespace.

Note: If you’re using Google Kubernetes Engine, you’ll need to grant permissions to the account that will be setting up Emissary. To do this, get your official GKE username, and then grant cluster-admin role privileges to that username:

kubectl create clusterrolebinding my-cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format="value(config.account)")

Then, you can deploy Emissary. Start by installing CRDs required by Emissary:

kubectl apply -f https://app.getambassador.io/yaml/ambassador-docs/$version$/ambassador/ambassador-crds.yaml

Then, apply the RBAC configuration with:

kubectl apply -f https://app.getambassador.io/yaml/ambassador-docs/$version$/ambassador/ambassador-rbac.yaml

We recommend downloading the YAML files and exploring the content. You will see that an ambassador-admin NodePort Service is created (which provides an Emissary ODD Diagnostic web UI), along with an ambassador ClusterRole, ServiceAccount, and ClusterRoleBinding. An Ambassador Deployment is also created.

When not installing Emissary into the default namespace you must update the namespace used in the ClusterRoleBinding.

For production configurations, we recommend you download these YAML files as your starting point, and customize them accordingly.

2. Defining the Emissary Service

The Emissary service is deployed as a Kubernetes Service that references the Emissary Deployment you deployed previously. Create the following YAML and put it in a file calledambassador-service.yaml.

---
apiVersion: v1
kind: Service
metadata:
  name: ambassador
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  ports:
   - port: 80
     targetPort: 8080
  selector:
    service: ambassador

Deploy this service with kubectl:

$ kubectl apply -f ambassador-service.yaml

The YAML above creates a Kubernetes service for Emissary of type LoadBalancer, and configures the externalTrafficPolicy to propagate the original source IP of the client. All HTTP traffic will be evaluated against the routing rules you create. Note that if you’re not deploying in an environment where LoadBalancer is a supported type (such as minikube), you’ll need to change this to a different type of service, e.g., NodePort.

If you have a static IP provided by your cloud provider you can set as loadBalancerIP.

3. The Diagnostics Service in Kubernetes

Emissary includes an integrated diagnostics service to help with troubleshooting.

By default, this is exposed to the internet at the URL http://{{AMBASSADOR_HOST}}/ambassador/v0/diag/. Go to that URL from a web browser to view the diagnostic UI.

You can change the default so it is not exposed externally by default by setting diagnostics.enabled: false in the ambassador Module.

apiVersion: getambassador.io/v2
kind: Module
metadata:
  name: ambassador
spec:
  config:
    diagnostics:
      enabled: false

After applying this Module, to view the diagnostics UI, we’ll need to get the name of one of the Emissary pods:

$ kubectl get pods
NAME                          READY     STATUS    RESTARTS   AGE
ambassador-3655608000-43x86   1/1       Running   0          2m
ambassador-3655608000-w63zf   1/1       Running   0          2m

Forwarding local port 8877 to one of the pods:

kubectl port-forward ambassador-3655608000-43x86 8877

will then let us view the diagnostics at http://localhost:8877/ambassador/v0/diag/.

4. Enable HTTPS

The versatile HTTPS configuration of Emissary lets it support various HTTPS use cases whether simple or complex.

See the TLS HOWTO to quickly enable HTTPS support for your applications.

Note that Ambassador Edge Stack automatically enables HTTPs. Read more about its configuration on the Host CRD page.

Helm

In the following instructions, we’ll install the open-source Emissary with Helm.

Although the Helm chart installs Ambassador Edge Stack by default, Emissary is still available for installation for both Helm 2 and Helm 3.

With Helm 2, you must enable CRD creation with the crd-install hook that is included in the CRD manifests. When installing with Helm 3, the following message will be output to stderr:

manifest_sorter.go:175: info: skipping unknown hook: "crd-install"

Because this hook is required for Helm 2 support, it IS NOT AN ERROR AND CAN BE SAFELY IGNORED.

To get started on Helm:

1. Add the Datawire repo to your Helm repositories
2. Install Emissary

1. Add the Datawire repo to your Helm repositories

helm repo add datawire https://www.getambassador.io

2. Install Emissary

Ambassador Edge Stack is installed by default. To install Emissary instead, change the image to point to the OSS image and set enableAES: false in the values.yaml file.

For example:

image:
  repository: docker.io/datawire/ambassador
  tag: $version$
enableAES: false

Then, install the chart using the values.yaml file:

helm install ambassador datawire/ambassador -f values.yaml

You can also install the chart with the --set flag:

helm install ambassador datawire/ambassador --set image.repository=docker.io/datawire/ambassador --set image.tag=$version$ --set enableAES=false

Kubernetes distributions

Emissary is currently available out-of-the-box in some Kubernetes distributions. See the integrations with community projects to quickly install Emissary.

Set up Service Catalog

Set up Service Catalog to view all of your service metadata in Ambassador Cloud.

Want more?

For more features, check out the latest build of the Emissary.