Server Name Indication (SNI) and Ingress TLS in Kubernetes with Ambassador

The open-source Ambassador 0.50 API gateway adds support for Server Name Indication (SNI), a much-requested feature from the community that allows the configuration of multiple TLS certificates to be served from a single ingress IP address. In this tutorial, we explore how multiple secure domains (e.g., https://www.datawire.io and https://www.getambassador.io.) can be provided by a single or load balanced Ambassador running within a Kubernetes cluster.

SNI Use Cases

In a nutshell (and with thanks to Wikipedia), SNI is an extension to the TLS protocol, which allows a client to indicate which hostname it is attempting to connect to at the start of the TCP handshaking process. This allows the server to present multiple certificates on the same IP address and TCP port number, which in turn enables the serving of multiple secure websites or API services without requiring all those sites to use the same certificate.

For those of you who have configured edge proxies and API gateways in the past, SNI is the conceptual equivalent to HTTP/1.1 name-based virtual hosting, but for HTTPS.

We’ve discussed many interesting use cases for SNI support within an edge proxy/gateway with both open-source and commercially-supported users of Ambassador.

Many engineers are running Kubernetes clusters that offer multiple backend services to end-users, and frequently, they want to serve secure traffic while presenting multiple hostnames as, for example, this allows the easy differentiation of services (e.g. www.datawire.io and api.dw.io) on offer and supports the exposure of multiple in-house (web addressable) brands that share backend services from a single cluster (e.g. www.fashion-brand-one.com and www.fashion-brand-two.com).

Configuring SNI in Ambassador

The Ambassador SNI documentation provides a step-by-step guide to the configuration and also covers ingress TLS termination in-depth, but I’ve also provided a summary here.

The first step is to create a TLS certificate for each of your required, secure transport contexts — typically, this would involve generating a certificate for each of your top-level domains — and add these certificates as Kubernetes secrets (e.g. datawire-site-secret and getambassador-site-secret).

Next, create a TLSContext resource and apply this configuration into your cluster:

---
apiVersion: v1
kind: Service
metadata:
  annotations:
    getambassador.io/config: |
    ---
    apiVersion: ambassador/v0
    kind: TLSContext
    name: datawire-site-context
    hosts:
    - www.datawire.io
    secret: datawire-site-secret
    ---
    apiVersion: ambassador/v0
    kind: TLSContext
    name: getambassador-site-context
    hosts:
    - www.getambassador.io
    secret: getambassador-site-secret
  <snip>

Note that, as detailed in the Ambassador TLS docs, the global TLS configuration may need to be updated in the tls module in order to redirect an insecure clear text request from, for example, port 80 to port 443 (other functionality, such as client-side authentication can also be configured here, too).

With the TLSContexts in place, the Ambassador Mappings for hosts and routes can now be specified and linked to the TLS contexts via the hosts:

---
apiVersion: v1
kind: Service
metadata:
  annotations:
    getambassador.io/config: |
      ---
      apiVersion: ambassador/v0
      kind:  Mapping
      name:  datawire-website-mapping
      prefix: /
      service: datawire-site-service:80
      host: www.datawire.io
      ---
      apiVersion: ambassador/v0
      kind:  Mapping
      name:  getambassador-website-mapping
      prefix: /
      service: getambassador-site-service.org:80
      host: www.getambassador.io
 <snip>

Upgrading to Ambassador 0.50 GA and SNI

Ambassador 0.50 GA is coming soon, and some of the additional functionality and architectural changes (such as supporting the Envoy v2 APIs and ADS) have required changes that are not backward compatible with older versions of Ambassador. We encourage you to test out the release candidates, read the release documentation, and validate your use cases before deploying this version into production (for example, via smoke tests and traffic shadowing).

We’re excited to see SNI functionality included within Ambassador, as this has been a popular feature request. We would like to thank all of the contributors and people who have discussed this feature on the Datawire Slack and GitHub repositories.