Ingress controller

An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an ingress controller. Emissary-ingress can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem.

When and how to use the Ingress resource

If you're new to Emissary-ingress and to Kubernetes, we'd recommend you start with our quickstart instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of Emissary-ingress, so you'll be using both the Ingress resource and Emissary-ingress's Mapping resource to manage your Kubernetes services.

What is required to use the Ingress resource?

• Know what version of Kubernetes you are using.

  • In Kubernetes 1.13 and below, the Ingress was only included in the extensions API.

  • Starting in Kubernetes 1.14, the Ingress was added to the new networking.k8s.io API.

  • Kubernetes 1.18 introduced the IngressClass resource to the existing networking.k8s.io/v1beta1 API.

  If you are using 1.14 and above, it is recommended to use apiVersion: networking.k8s.io/v1beta1 when defining an Ingress. Since both are still supported in all 1.14+ versions of Kubernetes, this document will use extensions/v1beta1 for compatibility reasons. If you are using 1.18 and above, sample usage of the IngressClass resource and pathType field are available on our blog.

• You will need RBAC permissions to create Ingress resources in either the extensions apiGroup (present in all supported versions of Kubernetes) or the networking.k8s.io apiGroup (introduced in Kubernetes 1.14).

• Emissary-ingress will need RBAC permissions to get, list, watch, and update Ingress resources.

  You can see this in the aes-crds.yaml file, but this is the critical rule to add to Emissary-ingress's Role or ClusterRole:

  This is included by default in all Emissary-ingress installations.

• You must create your Ingress resource with the correct ingress.class.

  Emissary-ingress will automatically read Ingress resources with the annotation kubernetes.io/ingress.class: ambassador.

• You may need to set your Ingress resource's ambassador-id.

  If you are using amabssador-id on your Module, you'll need to add the getambassador.io/ambassador-id annotation to your Ingress. See the examples below.

• You must create a Service resource with the correct app.kubernetes.io/component label.

  Emissary-ingress will automatically load balance Ingress resources using the endpoint exposed from the Service with the annotation app.kubernetes.io/component: ambassador-service.

When to use an Ingress instead of annotations or CRDs

We recommend that Emissary-ingress be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the Emissary-ingress Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). When in doubt, use CRDs.

Ingress support

Emissary-ingress supports basic core functionality of the Ingress resource, as defined by the Ingress resource itself:

• Basic routing is supported, including the route specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the Emissary-ingress diagnostic UI.
• TLS termination is supported. You can use multiple Ingress resources for SNI.
• Using the Ingress resource in concert with Emissary-ingress CRDs or annotations is supported. This includes Emissary-ingress annotations on the Ingress resource itself.

Emissary-ingress does not extend the basic Ingress specification with the following exceptions:

• The getambassador.io/ambassador-id annotation allows you to set the Ambassador ID for the Ingress itself.

• The getambassador.io/config annotation can be provided on the Ingress resource, just as on a Service.

Note that if you need to set getambassador.io/ambassador-id on the Ingress, you will also need to set ambassador-id on resources within the annotation.

Examples of Ingress configs vs Mapping configs

Ingress routes and Mappings

Emissary-ingress actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs exactly as they would if the Ingress route rules had been specified with CRDs originally.

For example, this Ingress resource routes traffic to /foo/ to service1:

This is the equivalent configuration using a Mapping instead:

This YAML will set up Emissary-ingress to do canary routing where 50% of the traffic will go to service1 and 50% will go to service2.

The minimal Ingress

An Ingress resource must provide at least some routes or a default backend. The default backend provides for a simple way to direct all traffic to some upstream service:

This is the equivalent configuration using a Mapping instead:

Name based virtual hosting with an Ambassador ID

This Ingress resource will result in all requests to foo.bar.com going to service1, and requests to bar.foo.com going to service2:

This is the equivalent configuration using a Mapping instead:

Read more on the Kubernetes documentation on name based virtual routing.

TLS termination

This is the equivalent configuration using a Mapping instead:

Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the Kubernetes docs on TLS termination.