Install Emissary-ingress

The Ambassador Edge Stack is now available and includes additional functionality beyond the current Emissary-ingress. 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-ingress, 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-ingress.

Install Emissary-ingress

• Kubernetes YAML
• Helm
• Kubernetes distributions

Kubernetes YAML

In this tutorial, we'll walk through the process of deploying Emissary-ingress in Kubernetes for ingress routing. Emissary-ingress 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-ingress 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-ingress reads to configure its Envoy Proxy.

Below, we'll configure Emissary-ingress to map /httpbin/ to httpbin.org.

1. Deploying Emissary-ingress

The following steps deploy Emissary-ingress 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-ingress. To do this, get your official GKE username, and then grant cluster-admin role privileges to that username:

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

Then, apply the RBAC configuration with:

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-ingress ODD Diagnostic web UI), along with an ambassador ClusterRole, ServiceAccount, and ClusterRoleBinding. An Ambassador Deployment is also created.

When not installing Emissary-ingress 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-ingress Service

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

Deploy this service with kubectl:

The YAML above creates a Kubernetes service for Emissary-ingress 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-ingress 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.

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

Forwarding local port 8877 to one of the pods:

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

4. Enable HTTPS

The versatile HTTPS configuration of Emissary-ingress 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-ingress with Helm.

Although the Helm chart installs Ambassador Edge Stack by default, Emissary-ingress 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:

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-ingress

1. Add the Datawire repo to your Helm repositories

2. Install Emissary-ingress

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

For example:

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

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

Kubernetes distributions

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

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 Ambassador Edge Stack.