This is the documentation for the latest development version of Contour. Both code and docs may be unstable, and these docs are not guaranteed to be up to date or correct. See the latest version.
HTTPProxy follows a similar pattern to Ingress for configuring TLS credentials.
You can secure a HTTPProxy by specifying a Secret that contains TLS private key and certificate information. If multiple HTTPProxies utilize the same Secret, the certificate must include the necessary Subject Authority Name (SAN) for each fqdn.
Contour (via Envoy) requires that clients send the Server Name Indication (SNI) TLS extension so that requests can be routed to the correct virtual host. Virtual hosts are strongly bound to SNI names. This means that the Host header in HTTP requests must match the SNI name that was sent at the start of the TLS session.
Contour also follows a “secure first” approach.
When TLS is enabled for a virtual host, any request to the insecure port is redirected to the secure interface with a 301 redirect.
Specific routes can be configured to override this behavior and handle insecure requests by enabling the
spec.routes.permitInsecure parameter on a Route.
The TLS secret must contain keys named tls.crt and tls.key that contain the certificate and private key to use for TLS, e.g.:
# ingress-tls.secret.yaml apiVersion: v1 data: tls.crt: base64 encoded cert tls.key: base64 encoded key kind: Secret metadata: name: testsecret namespace: default type: kubernetes.io/tls
The HTTPProxy can be configured to use this secret using
# httpproxy-tls.yaml apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: tls-example namespace: default spec: virtualhost: fqdn: foo2.bar.com tls: secretName: testsecret routes: - services: - name: s1 port: 80
tls.secretName property contains a slash, eg.
somenamespace/somesecret then, subject to TLS Certificate Delegation, the TLS certificate will be read from
See TLS Certificate Delegation below for more information.
The TLS Minimum Protocol Version a virtual host should negotiate can be specified by setting the
Contour provides virtual host based routing, so that any TLS request is routed to the appropriate service based on both the server name requested by the TLS client and the HOST header in the HTTP request.
Since the HOST Header is encrypted during TLS handshake, it can’t be used for virtual host based routing unless the client sends HTTPS requests specifying hostname using the TLS server name, or the request is first decrypted using a default TLS certificate.
Some legacy TLS clients do not send the server name, so Envoy does not know how to select the right certificate. A fallback certificate is needed for these clients.
The minimum TLS protocol version for any fallback request is defined by the
minimum TLS protocol version set in the Contour configuration file.
Enabling the fallback certificate is not compatible with TLS client authentication.
First define the
namespace/name in the Contour configuration file of a Kubernetes secret which will be used as the fallback certificate.
Any HTTPProxy which enables fallback certificate delegation must have the fallback certificate delegated to the namespace in which the HTTPProxy object resides.
To do that, configure
TLSCertificateDelegation to delegate the fallback certificate to specific or all namespaces (e.g.
*) which should be allowed to enable the fallback certificate.
Finally, for each root HTTPProxy, set the
Spec.TLS.enableFallbackCertificate parameter to allow that HTTPProxy to opt-in to the fallback certificate routing.
apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: fallback-tls-example namespace: defaultub spec: virtualhost: fqdn: fallback.bar.com tls: secretName: testsecret enableFallbackCertificate: true routes: - services: - name: s1 port: 80 --- apiVersion: projectcontour.io/v1 kind: TLSCertificateDelegation metadata: name: fallback-delegation namespace: www-admin spec: delegations: - secretName: fallback-secret-name targetNamespaces: - "*"
A HTTPProxy can be configured to permit insecure requests to specific Routes.
In this example, any request to
foo2.bar.com/blog will not receive a 301 redirect to HTTPS, but the
/ route will:
apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: tls-example-insecure namespace: default spec: virtualhost: fqdn: foo2.bar.com tls: secretName: testsecret routes: - services: - name: s1 port: 80 - conditions: - prefix: /blog permitInsecure: true services: - name: s2 port: 80
It is possible to protect the backend service from unauthorized external clients by requiring the client to present a valid TLS certificate. Envoy will validate the client certificate by verifying that it is not expired and that a chain of trust can be established to the configured trusted root CA certificate. Only those requests with a valid client certificate will be accepted and forwarded to the backend service.
apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: with-client-auth spec: virtualhost: fqdn: www.example.com tls: secretName: secret clientValidation: caSecret: client-root-ca routes: - services: - name: s1 port: 80
The preceding example enables validation by setting the optional
Its mandatory attribute
caSecret contains a name of an existing Kubernetes Secret that must be of type “Opaque” and have a data key named
The data value of the key
ca.crt must be a PEM-encoded certificate bundle and it must contain all the trusted CA certificates that are to be used for validating the client certificate.
HTTPProxy supports proxying of TLS encapsulated TCP sessions.
Note: The TCP session must be encrypted with TLS. This is necessary so that Envoy can use SNI to route the incoming request to the correct service.
spec.virtualhost.tls.secretName is present then that secret will be used to decrypt the TCP traffic at the edge.
# httpproxy-tls-termination.yaml apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: example namespace: default spec: virtualhost: fqdn: tcp.example.com tls: secretName: secret tcpproxy: services: - name: tcpservice port: 8080 - name: otherservice port: 9999 weight: 20
spec.tcpproxy key indicates that this root HTTPProxy will forward the de-encrypted TCP traffic to the backend service.
If you wish to handle the TLS handshake at the backend service set
spec.virtualhost.tls.passthrough: true indicates that once SNI demuxing is performed, the encrypted connection will be forwarded to the backend service.
The backend service is expected to have a key which matches the SNI header received at the edge, and be capable of completing the TLS handshake. This is called SSL/TLS Passthrough.
# httpproxy-tls-passthrough.yaml apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: example namespace: default spec: virtualhost: fqdn: tcp.example.com tls: passthrough: true tcpproxy: services: - name: tcpservice port: 8080 - name: otherservice port: 9999 weight: 20