TLS Termination / Passthrough

Gateway API

The Gateway API supports both TLS termination and TLS passthrough. TLS handling is configured via a combination of a Gateway’s listeners[].tls.mode and the attached route type:

Passthrough mode listeners inspect the TLS stream hostname via server name indication and pass the TLS stream unaltered upstream. These listeners do not use certificate configuration. They only accept TLSRoutes.
Terminate mode listeners decrypt the TLS stream and inspect the request it wraps before passing it upstream. They require certificate Secret reference in the listeners[].tls.[]certificateRefs field. They accept HTTPRoutes, TCPRoutes, and GRPCRoutes.

To terminate TLS, create a Gateway with a listener with .tls.mode: "Terminate", create a TLS Secret and add it to the listener .tls.certificateRefs array, and then create one of the supported route types with matching criteria that will bind it to the listener.

For HTTPRoute or GRPCRoute, the route’s hostname must match the listener hostname. For TCPRoute the route’s port must match the listener port.

Ingress

The Ingress API supports TLS temination using the .spec.tls field. To terminate TLS with the Ingress API, provide .spec.tls.secretName that contains a TLS certificate and a list of .spec.tls.hosts to match in your Ingress definition.

Examples

TLS Termination

Gateway API

Ingress

Create a Gateway resource.

 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: example-gateway
 spec:
   gatewayClassName: kong 
   listeners:
   - name: https
     port: 443
     protocol: HTTPS
     hostname: "demo.example.com"
     tls:
       mode: Passthrough

Bind a HTTPRoute to the Gateway.

 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: demo-example 
 spec:
   parentRefs:
   - name: kong
     sectionName: https
   hostnames:
   - demo.example.com
   rules:
   - matches:
     - path:
         type: PathPrefix
         value: /echo
     backendRefs:
     - name: echo
       port: 1027

Kong Gateway will terminate TLS traffic before sending the request upstream.

Specify a secretName and list of hosts in .spec.tls.

 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
  name: demo-example-com
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
 spec:
  ingressClassName: kong
  tls:
  - secretName: demo-example-com
    hosts:
    - demo.example.com
  rules:
  - host: demo.example.com
    http:
      paths:
      - path: /
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 80

The results will look like this:

 ingress.extensions/demo-example-com configured

TLS Passthrough

Gateway API

Ingress

Create a Gateway resource.

 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: example-gateway
 spec:
   gatewayClassName: kong 
   listeners:
   - name: https
     port: 443
     protocol: HTTPS
     hostname: "demo.example.com"
     tls:
       mode: Passthrough
       certificateRefs:
       - kind: Secret
         name: example-com

Bind a TLSRoute to the Gateway.

 apiVersion: gateway.networking.k8s.io/v1alpha2
 kind: TLSRoute
 metadata:
   name: demo-example-passthrough
 spec:
   parentRefs:
   - name: kong
     sectionName: https
   hostnames:
   - demo.example.com
   rules:
   - backendRefs:
     - name: tlsecho
       port: 1989

You cannot use any matches rules on a TLSRoute as the TLS traffic has not been decrypted.

Kong Gateway will not terminate TLS traffic before sending the request upstream.

The Ingress API does not support TLS passthrough