The Host CRD

The custom Host resource defines how Ambassador Edge Stack will be visible to the outside world. It collects all the following information in a single configuration resource:

• The hostname by which Ambassador Edge Stack will be reachable
• How Ambassador Edge Stack should handle TLS certificates
• How Ambassador Edge Stack should handle secure and insecure requests
• Which Mappings should be associated with this Host

A minimal Host resource, using Let’s Encrypt to handle TLS, would be:

This Host tells Ambassador Edge Stack to expect to be reached at host.example.com, and to manage TLS certificates using Let’s Encrypt, registering as julian@example.com. Since it doesn’t specify otherwise, requests using cleartext will be automatically redirected to use HTTPS, and Ambassador Edge Stack will not search for any specific further configuration resources related to this Host.

Remember that a Listener will also be required for this example to be functional. Many examples of setting up Host and Listener are available in the Configuring Ambassador Edge Stack to Communicate document.

Setting the hostname

The hostname element tells Ambassador Edge Stack which hostnames to expect. hostname is a DNS glob, so all of the following are valid:

• host.example.com
• *.example.com
• host.example.*

The following are not valid:

• host.*.com -- Envoy supports only prefix and suffix globs
• *host.example.com -- the wildcard must be its own element in the DNS name

In all cases, the hostname is used to match the :authority header for HTTP routing. When TLS termination is active, the hostname is also used for SNI matching.

Controlling Association with Mappings

A Mapping will not be associated with a Host unless at least one of the following is true:

• The Mapping specifies a hostname attribute that matches the Host in question.
• The Host specifies a mappingSelector that matches the Mapping's Kubernetes labels.

Note: The mappingSelector field is only configurable on v3alpha1 CRDs. In the v2 CRDs the equivalent field is selector. either selector or mappingSelector may be configured in the v3alpha1 CRDs, but selector has been deprecated in favour of mappingSelector.

If neither of the above is true, the Mapping will not be associated with the Host in question. This is intended to help manage memory consumption with large numbers of Hosts and large numbers of Mappings.

If the Host specifies mappingSelector and the Mapping specifies hostname, both must match for the association to happen.

The mappingSelector is a Kubernetes label selector. For a Mapping to be associated with a Host that uses mappingSelector, then all labels required by the mappingSelector must be present on the Mapping in order for it to be associated with the Host. A Mapping may have additional labels other than those required by the mappingSelector so long as the required labels are present.

in 2.0, only matchLabels is supported, for example:

The above Host will associate with these Mappings:

It will not associate with any of these:

Future versions of Ambassador Edge Stack will support matchExpressions as well.

Note: In Ambassador Edge Stack version 3.2, a bug with how Hosts are associated with Mappings was fixed. The mappingSelector field in Hosts was not properly being enforced in prior versions. If any single label from the selector was matched then the Host would be associated with the Mapping instead of requiring all labels in the selector to be present. Additonally, if the hostname of the Mapping matched the hostname of the Host then they would be associated regardless of the configuration of mappingSelector. In version 3.2 this bug was fixed and a Host will only be associated with a Mapping if all labels required by the selector are present. This brings the mappingSelector field in-line with how label selectors are used throughout Kubernetes. To avoid unexpected behavior after the upgrade, add all labels that Hosts have in their mappingSelector to Mappings you want to associate with the Host. You can opt-out of this fix and return to the old Mapping/Host association behavior by setting the environment variable DISABLE_STRICT_LABEL_SELECTORS to "true" (default: "false"). A future version of Ambassador Edge Stack may remove the ability to opt-out of this bugfix.

Secure and insecure requests

A secure request arrives via HTTPS; an insecure request does not. By default, secure requests will be routed and insecure requests will be redirected (using an HTTP 301 response) to HTTPS. The behavior of insecure requests can be overridden using the requestPolicy element of a Host:

The insecure-action can be one of:

• Redirect (the default): redirect to HTTPS
• Route: go ahead and route as normal; this will allow handling HTTP requests normally
• Reject: reject the request with a 400 response

Some special cases to be aware of here:

• Case matters in the actions: you must use e.g. Reject, not reject.
• The X-Forwarded-Proto header is honored when determining whether a request is secure or insecure. For more information, see "Load Balancers, the Host Resource, and X-Forwarded-Proto" below.
• ACME challenges with prefix /.well-known/acme-challenge/ are always forced to be considered insecure, since they are not supposed to arrive over HTTPS.
• Ambassador Edge Stack provides native handling of ACME challenges. If you are using this support, Ambassador Edge Stack will automatically arrange for insecure ACME challenges to be handled correctly. If you are handling ACME yourself - as you must when running Emissary-ingress - you will need to supply appropriate Host resources and Mappings to correctly direct ACME challenges to your ACME challenge handler.

TLS settings

The Host is responsible for high-level TLS configuration in Ambassador Edge Stack. There are several settings covering TLS:

ACME support

Ambassador Edge Stack comes with built in support for automatic certificate management using the ACME protocol.

It does this by using the hostname of a Host to request a certificate from the acmeProvider.authority using the HTTP-01 challenge. After requesting a certificate, Ambassador Edge Stack will then manage the renewal process automatically.

The acmeProvider element of the Host configures the Certificate Authority Ambassador Edge Stack will request the certificate from and the email address that the CA will use to notify about any lifecycle events of the certificate.

Notes on ACME Support:

• If the authority is not supplied, the Let’s Encrypt production environment is assumed.

• In general, email-of-registrant is mandatory when using ACME: it should be a valid email address that will reach someone responsible for certificate management.

• ACME stores certificates in Kubernetes secrets. The name of the secret can be set using the tlsSecret element:

  if not supplied, a name will be automatically generated from the hostname and email.

• Ambassador Edge Stack uses the HTTP-01 challenge for ACME support:

  • Does not require permission to edit DNS records
  • The hostname must be reachable from the internet so the CA can check POST to an endpoint in Ambassador Edge Stack.
  • Wildcard domains are not supported.

tlsSecret enables TLS termination

tlsSecret specifies a Kubernetes Secret is required for any TLS termination to occur. If ACME is enabled, it will set tlsSecret: in all other cases, TLS termination will not occur if tlsSecret is not specified.

The following Host will configure Ambassador Edge Stack to read a Secret named tls-cert for a certificate to use when terminating TLS.

tlsContext links to a TLSContext for additional configuration

tlsContext specifies a TLSContext to use for additional TLS information. Note that you must still define tlsSecret for TLS termination to happen. It is an error to supply both tlsContext and tls.

See the TLS discussion for more details.

tls allows manually providing additional configuration

tls allows specifying most of the things a TLSContext can, inline in the Host. Note that you must still define tlsSecret for TLS termination to happen. It is an error to supply both tlsContext and tls.

See the TLS discussion for more details.

Load balancers, the Host resource, and X-Forwarded-Proto

In a typical installation, Ambassador Edge Stack runs behind a load balancer. The configuration of the load balancer can affect how Ambassador Edge Stack sees requests arriving from the outside world, which can in turn can affect whether Ambassador Edge Stack considers the request secure or insecure. As such:

• We recommend layer 4 load balancers unless your workload includes long-lived connections with multiple requests arriving over the same connection. For example, a workload with many requests carried over a small number of long-lived gRPC connections.
• Ambassador Edge Stack fully supports TLS termination at the load balancer with a single exception, listed below.
• If you are using a layer 7 load balancer, it is critical that the system be configured correctly:
  • The load balancer must correctly handle X-Forwarded-For and X-Forwarded-Proto.
  • The l7Depth element in the Listener CRD must be set to the number of layer 7 load balancers the request passes through to reach Ambassador Edge Stack (in the typical case, where the client speaks to the load balancer, which then speaks to Ambassador Edge Stack, you would set l7Depth to 1). If l7Depth remains at its default of 0, the system might route correctly, but upstream services will see the load balancer's IP address instead of the actual client's IP address.

It's important to realize that Envoy manages the X-Forwarded-Proto header such that it always reflects the most trustworthy information Envoy has about whether the request arrived encrypted or unencrypted. If no X-Forwarded-Proto is received from downstream, or if it is considered untrustworthy, Envoy will supply an X-Forwarded-Proto that reflects the protocol used for the connection to Envoy itself. The l7Depth element is also used when determining trust for X-Forwarded-For, and it is therefore important to set it correctly. Its default of 0 should always be correct when Ambassador Edge Stack is behind only layer 4 load balancers; it should need to be changed only when layer 7 load balancers are involved.

CRD specification

The Host CRD is formally described by its protobuf specification. Developers who need access to the specification can find it here.