Gateway API allow 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.
TLSRoute resource described below is currently only included in the
"Experimental" channel of Gateway API. For more information on release
channels, refer to the related documentation.
Client/Server and TLS¶
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.
Depending on the Listener Protocol, different TLS modes and Route types are supported.
|Listener Protocol||TLS Mode||Route Type Supported|
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.
The rest of the document assumes that TLS is being terminated at the Gateway,
which is the default setting.
Downstream TLS settings are configured using listeners at the Gateway level.
Listeners and TLS¶
Listeners expose the TLS setting on a per domain or sub-domain basis.
TLS settings of a listener are applied to all domains that satisfy the
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.
listeners: - protocol: HTTPS # Other possible value is `TLS` port: 443 tls: mode: Terminate # If protocol is `TLS`, `Passthrough` is a possible mode certificateRef: kind: Secret group: "" name: default-cert
hostname.match is set to
Exact, then the TLS settings apply to only the
specific hostname that is set in
Listeners with different certificates¶
In this example, the Gateway is configured to serve the
bar.example.com domains. The certificate for these domains is specified
in the Gateway.
apiVersion: gateway.networking.k8s.io/v1beta1 kind: Gateway metadata: name: tls-basic spec: gatewayClassName: acme-lb listeners: - name: foo-https protocol: HTTPS port: 443 hostname: foo.example.com tls: certificateRefs: - kind: Secret group: "" name: foo-example-com-cert - name: bar-https protocol: HTTPS port: 443 hostname: bar.example.com tls: certificateRefs: - kind: Secret group: "" 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
Since a specific match takes priority, the Gateway will serve
foo-example-com-cert for requests to
wildcard-example-com-cert for all other requests.
apiVersion: gateway.networking.k8s.io/v1beta1 kind: Gateway metadata: name: wildcard-tls-gateway spec: gatewayClassName: acme-lb listeners: - name: foo-https protocol: HTTPS port: 443 hostname: foo.example.com tls: certificateRefs: - kind: Secret group: "" name: foo-example-com-cert - name: wildcard-https protocol: HTTPS port: 443 hostname: "*.example.com" tls: certificateRefs: - kind: Secret group: "" 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.
apiVersion: gateway.networking.k8s.io/v1alpha2 kind: Gateway metadata: name: cross-namespace-tls-gateway namespace: gateway-api-example-ns1 spec: gatewayClassName: acme-lb listeners: - name: https protocol: HTTPS port: 443 hostname: "*.example.com" tls: certificateRefs: - kind: Secret group: "" name: wildcard-example-com-cert namespace: gateway-api-example-ns2 --- apiVersion: gateway.networking.k8s.io/v1alpha2 kind: ReferenceGrant metadata: name: allow-ns1-gateways-to-ref-secrets namespace: gateway-api-example-ns2 spec: from: - group: gateway.networking.k8s.io kind: Gateway namespace: gateway-api-example-ns1 to: - group: "" kind: Secret
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.