Transport Layer Security (TLS)

Ambassador Edge Stack's robust TLS support exposes configuration options for different TLS use cases including:

• Simultaneously Routing HTTP and HTTPS
• HTTP -> HTTPS Redirection
• Mutual TLS
• Server Name Indication (SNI)
• TLS Origination

Host

A Host represents a domain in Ambassador Edge Stack and defines how the domain manages TLS. For more information on the Host resource, see The Host CRD reference documentation.

In Ambassador Edge Stack, the simplest configuration of a Host will enable TLS with a self-signed certificate and redirect cleartext traffic to HTTPS.

The example below does not define a requestPolicy; however, this is something to keep in mind as you begin using the Host CRD in Ambassador Edge Stack.

For more information, please refer to the Host documentation.

Automatic TLS with ACME

With Ambassador Edge Stack, you can configure the Host to manage TLS by requesting a certificate from a Certificate Authority using the ACME HTTP-01 challenge.

After you create a DNS record, configure Ambassador Edge Stack to get a certificate from the default CA, Let's Encrypt, by providing a hostname and your email for the certificate:

Ambassador Edge Stack will now request a certificate from the CA and store it in a Secret in the same namespace as the Host.

Bring your own certificate

For both Ambassador Edge Stack and Emissary-ingress, the Host can read a certificate from a Kubernetes secret and use that certificate to terminate TLS on a domain.

The following will configure Ambassador Edge Stack to grab a certificate from a secret named host-secret and use that secret for terminating TLS on the host.example.com domain:

Advanced TLS configuration with the Host

You can specify TLS configuration directly in the Host via the tls field. This is the recommended method for more advanced TLS Configuration.

For example, the configuration to enforce a minimum TLS version on the Host looks as follows:

The following fields are accepted in the tls field:

Host and TLSContext

The Host will configure most TLS termination settings in Ambassador Edge Stack.

If you require TLS configuration that is not available via the above tls settings in a Host, you can create a TLSContext and associate it with a Host with either of the following two methods.

Note: It is invalid to configure both spec.tls and spec.tlsContext.name on a Host. It is recommended to configure the tls setting in a Host without creating any TLSContext objects unless necessary. If you need to link a TLSContext to a Host make sure you are not also configuring the tls settings in that Host.

Create a TLSContext with the name {{AMBASSADORHOST}}-context

You can create a TLSContext with the name {{NAME_OF_AMBASSADORHOST}}-context, hosts set to the same hostname, and secret set to the same tlsSecret.

For example, to enforce a minimum TLS version on the Host above, create a TLSContext named example-host-context with the following configuration:

Full reference for all options available to the TLSContext can be found below.

Link a TLSContext to the Host

You can create a new TLSContext with the desired configuration and link it to the Host via the tlsContext field.

For example, to enforce a minimum TLS version on the Host above, create a TLSContext with any name with the following configuration:

Next, link it to the Host via the tlsContext field as shown:

Note: Any hosts or secret in the TLSContext must be the compatible with the Host to which it is being linked.

See TLSContext below to read more on the description of these fields.

TLSContext

The TLSContext is used to configure advanced TLS options in Ambassador Edge Stack. Remember, a TLSContext should always be paired with a Host.

A full schema of the TLSContext can be found below with descriptions of the different configuration options.

ALPN protocols

The alpn_protocols setting configures the TLS ALPN protocol. To use gRPC over TLS, set alpn_protocols: h2. If you need to support HTTP/2 upgrade from HTTP/1, set alpn_protocols: h2,http/1.1 in the configuration.

HTTP/2 support

The alpn_protocols setting is also required for HTTP/2 support.

Without setting alpn_protocols as shown above, HTTP2 will not be available via negotiation and will have to be explicitly requested by the client.

If you leave off http/1.1, only HTTP2 connections will be supported.

TLS parameters

The min_tls_version setting configures the minimum TLS protocol version that Ambassador Edge Stack will use to establish a secure connection. When a client using a lower version attempts to connect to the server, the handshake will result in the following error: tls: protocol version not supported.

The max_tls_version setting configures the maximum TLS protocol version that Ambassador Edge Stack will use to establish a secure connection. When a client using a higher version attempts to connect to the server, the handshake will result in the following error: tls: server selected unsupported protocol version.

The cipher_suites setting configures the supported ciphers found below using the configuration parameters for BoringSSL when negotiating a TLS 1.0-1.2 connection. This setting has no effect when negotiating a TLS 1.3 connection. When a client does not support a matching cipher a handshake error will result.

The ecdh_curves setting configures the supported ECDH curves when negotiating a TLS connection. When a client does not support a matching ECDH a handshake error will result.

TLS Module (Deprecated)

The TLS Module is deprecated. TLSContext should be used when using Ambassador Edge Stack version 0.50.0 and above.

For users of Ambassador Edge Stack, see the Host CRD reference for more information.