DocsEdge Stack1.14Transport Layer Security (TLS)
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
As explained in the Host reference, a Host
represents a domain
in Ambassador Edge Stack and defines how TLS is managed on that domain. In Ambassador Edge Stack, the simplest configuration of a Host
will enable TLS with a
self-signed certificate and redirect cleartext traffic to HTTPS.
WARNING - Host Configuration: The
requestPolicy
property of theHost
CRD
is applied globally within an Ambassador Edge Stack instance, even if it is applied to only oneHost
when multipleHost
s are configured. DifferentrequestPolicy
behaviors cannot be applied to differentHost
s. It is recommended to apply an identicalrequestPolicy
to allHost
s instead of assuming the behavior, to create a more human readable config.If a requestPolicy is not defined for a
Host
, it's assumed to beRedirect
, so even if aHost
does not specify it, the defaultrequestPolicy
ofRedirect
will be applied to allHost
s in that Ambassador Edge Stack instance. If the behavior expected out of Ambassador Edge Stack is anything other thanRedirect
, it must be explicitly enumerated in all Host resources.Unexpected behavior can occur when multiple
Host
resources are not using the same value forrequestPolicy
.The
insecure-action
can be one of:
Redirect
(the default): redirect to HTTPSRoute
: go ahead and route as normal; this will allow handling HTTP requests normallyReject
: reject the request with a 400 responseThe example below does not define a
requestPolicy
; however, this is something to keep in mind as you begin using theHost
CRD
in Ambassador Edge Stack.For more information, please refer to the
Host
documentation.
Automatic TLS with ACME
With Ambassador Edge Stack, the Host can be configured to completely manage TLS by requesting a certificate from a Certificate Authority using the ACME HTTP-01 challenge.
After creating a DNS record, configuring Ambassador Edge Stack to get a certificate from the default CA Let's Encrypt is as simple as 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:
Ambassador Edge Stack will now use the certificate in host-secret
to terminate TLS.
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, to enforce a minimum TLS version on the Host
, the configuration will look like this:
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
andspec.tlsContext.name
on aHost
. It is recommended to configure thetls
setting in aHost
without creating anyTLSContext
objects unless necessary. If you need to link aTLSContext
to aHost
make sure you are not also configuring thetls
settings in thatHost
.
Create a TLSContext
with the name {{HOST}}-context
You can create a TLSContext
with the name
{{NAME_OF_HOST}}-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:
and 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.
ON THIS PAGE