TLS Configuration

Gateway API allows for a variety of ways to configure TLS. This document lays out various TLS settings and gives general guidelines on how to use them effectively.

Although this doc covers the most common forms of TLS configuration with Gateway API, some implementations may also offer implementation-specific extensions that allow for different or more advanced forms of TLS configuration. In addition to this documentation, it’s worth reading the TLS documentation for whichever implementation(s) you’re using with Gateway API.

Experimental Channel

The TLSRoute and BackendTLSPolicy resources described below are currently only included in the “Experimental” channel of Gateway API. For more information on release channels, refer to our versioning guide.

Client/Server and TLS

overview

For Gateways, there are two connections involved:

  • downstream: This is the connection between the client and the Gateway.
  • upstream: This is the connection between the Gateway and backend resources specified by routes. These backend resources will usually be Services.

With Gateway API, TLS configuration of downstream and upstream connections is managed independently.

For downstream connections, depending on the Listener Protocol, different TLS modes and Route types are supported.

Listener ProtocolTLS ModeRoute Type Supported
TLSPassthroughTLSRoute
TLSTerminateTCPRoute
HTTPSTerminateHTTPRoute
GRPCTerminateGRPCRoute

Please note that in case of Passthrough TLS mode, no TLS settings take effect as the TLS session from the client is NOT terminated at the Gateway, but rather passes through the Gateway, encrypted.

For upstream connections, BackendTLSPolicy is used, and neither listener protocol nor TLS mode apply to the upstream TLS configuration. For HTTPRoute, the use of both Terminate TLS mode and BackendTLSPolicy is supported. Using these together provides what is commonly known as a connection that is terminated and then re-encrypted at the Gateway.

Downstream TLS

Downstream TLS settings are configured using listeners at the Gateway level.

Listeners and TLS

Listeners expose the TLS setting on a per domain or subdomain basis. TLS settings of a listener are applied to all domains that satisfy the hostname criteria.

In the following example, the Gateway serves the TLS certificate defined in the default-cert Secret resource for all requests. Although the example refers to HTTPS protocol, one can also use the same feature for TLS-only protocol along with TLSRoutes.

  1. listeners:
  2. - protocol: HTTPS # Other possible value is `TLS`
  3.   port: 443
  4.   tls:
  5.     mode: Terminate # If protocol is `TLS`, `Passthrough` is a possible mode
  6.     certificateRefs:
  7.     - kind: Secret
  8.       group: ""
  9.       name: default-cert

Examples

Listeners with different certificates

In this example, the Gateway is configured to serve the foo.example.com and bar.example.com domains. The certificate for these domains is specified in the Gateway.

  1. apiVersion: gateway.networking.k8s.io/v1
  2. kind: Gateway
  3. metadata:
  4.   name: tls-basic
  5. spec:
  6.   gatewayClassName: example
  7.   listeners:
  8.   - name: foo-https
  9.     protocol: HTTPS
  10.     port: 443
  11.     hostname: foo.example.com
  12.     tls:
  13.       certificateRefs:
  14.       - kind: Secret
  15.         group: ""
  16.         name: foo-example-com-cert
  17.   - name: bar-https
  18.     protocol: HTTPS
  19.     port: 443
  20.     hostname: bar.example.com
  21.     tls:
  22.       certificateRefs:
  23.       - kind: Secret
  24.         group: ""
  25.         name: bar-example-com-cert

Wildcard TLS listeners

In this example, the Gateway is configured with a wildcard certificate for *.example.com and a different certificate for foo.example.com. Since a specific match takes priority, the Gateway will serve foo-example-com-cert for requests to foo.example.com and wildcard-example-com-cert for all other requests.

  1. apiVersion: gateway.networking.k8s.io/v1
  2. kind: Gateway
  3. metadata:
  4.   name: wildcard-tls-gateway
  5. spec:
  6.   gatewayClassName: example
  7.   listeners:
  8.   - name: foo-https
  9.     protocol: HTTPS
  10.     port: 443
  11.     hostname: foo.example.com
  12.     tls:
  13.       certificateRefs:
  14.       - kind: Secret
  15.         group: ""
  16.         name: foo-example-com-cert
  17.   - name: wildcard-https
  18.     protocol: HTTPS
  19.     port: 443
  20.     hostname: "*.example.com"
  21.     tls:
  22.       certificateRefs:
  23.       - kind: Secret
  24.         group: ""
  25.         name: wildcard-example-com-cert

Cross namespace certificate references

In this example, the Gateway is configured to reference a certificate in a different namespace. This is allowed by the ReferenceGrant created in the target namespace. Without that ReferenceGrant, the cross-namespace reference would be invalid.

  1. apiVersion: gateway.networking.k8s.io/v1
  2. kind: Gateway
  3. metadata:
  4.   name: cross-namespace-tls-gateway
  5.   namespace: gateway-api-example-ns1
  6. spec:
  7.   gatewayClassName: example
  8.   listeners:
  9.   - name: https
  10.     protocol: HTTPS
  11.     port: 443
  12.     hostname: "*.example.com"
  13.     tls:
  14.       certificateRefs:
  15.       - kind: Secret
  16.         group: ""
  17.         name: wildcard-example-com-cert
  18.         namespace: gateway-api-example-ns2
  19. ---
  20. apiVersion: gateway.networking.k8s.io/v1beta1
  21. kind: ReferenceGrant
  22. metadata:
  23.   name: allow-ns1-gateways-to-ref-secrets
  24.   namespace: gateway-api-example-ns2
  25. spec:
  26.   from:
  27.   - group: gateway.networking.k8s.io
  28.     kind: Gateway
  29.     namespace: gateway-api-example-ns1
  30.   to:
  31.   - group: ""
  32.     kind: Secret

Upstream TLS

Upstream TLS settings are configured using the experimental BackendTLSPolicy attached to a Service via a target reference.

This resource can be used to describe the SNI the Gateway should use to connect to the backend and how the certificate served by the backend Pod(s) should be verified.

TargetRefs and TLS

BackendTLSPolicy contains specification for the TargetRefs and Validation. TargetRefs is required and identifies one or more Services for which your HTTPRoute requires TLS. The Validation configuration contains a required Hostname, and either CACertificateRefs or WellKnownCACertificates.

Hostname refers to the SNI the Gateway should use to connect to the backend, and must match the certificate served by the backend pod.

CACertificateRefs refer to one or more PEM-encoded TLS certificates. If there are no specific certificates to use, then you must set WellKnownCACertificates to “System” to tell the Gateway to use a set of trusted CA Certificates. There may be some variation in which system certificates are used by each implementation. Refer to documentation from your implementation of choice for more information.

Restrictions

  • Cross-namespace certificate references are not allowed.
  • Wildcard hostnames are not allowed.

Examples

Using System Certificates

In this example, the BackendTLSPolicy is configured to use system certificates to connect with a TLS-encrypted upstream connection where Pods backing the dev Service are expected to serve a valid certificate for dev.example.com.

  1. apiVersion: gateway.networking.k8s.io/v1alpha3
  2. kind: BackendTLSPolicy
  3. metadata:
  4.   name: tls-upstream-dev
  5. spec:
  6.   targetRefs:
  7.     - kind: Service
  8.       name: dev
  9.       group: ""
  10.   validation:
  11.     wellKnownCACertificates: "System"
  12.     hostname: dev.example.com

Using Explicit CA Certificates

In this example, the BackendTLSPolicy is configured to use certificates defined in the configuration map auth-cert to connect with a TLS-encrypted upstream connection where Pods backing the auth Service are expected to serve a valid certificate for auth.example.com.

  1. apiVersion: gateway.networking.k8s.io/v1alpha3
  2. kind: BackendTLSPolicy
  3. metadata:
  4.   name: tls-upstream-auth
  5. spec:
  6.   targetRefs:
  7.     - kind: Service
  8.       name: auth
  9.       group: ""
  10.   validation:
  11.     caCertificateRefs:
  12.       - kind: ConfigMap
  13.         name: auth-cert
  14.         group: ""
  15.     hostname: auth.example.com

Extensions

Gateway TLS configurations provides an options map to add additional TLS settings for implementation-specific features. Some examples of features that could go in here would be TLS version restrictions, or ciphers to use.