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 termination 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

Prerequisites: Install Kong Ingress Controller with Gateway API support in your Kubernetes cluster and connect to Kong.

Prerequisites

Install the Gateway APIs

Install the experimental Gateway API CRDs before installing Kong Ingress Controller.

 kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/experimental-install.yaml

Create a Gateway and GatewayClass instance to use.

echo "
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: kong
  annotations:
    konghq.com/gatewayclass-unmanaged: 'true'

spec:
  controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
spec:
  gatewayClassName: kong
  listeners:
  - name: proxy
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
         from: All
" | kubectl apply -f -

The results should look like this:

gatewayclass.gateway.networking.k8s.io/kong created
gateway.gateway.networking.k8s.io/kong created

Install Kong

You can install Kong in your Kubernetes cluster using Helm.

Add the Kong Helm charts:

 helm repo add kong https://charts.konghq.com
 helm repo update

Install Kong Ingress Controller and Kong Gateway with Helm:

 helm install kong kong/ingress -n kong --create-namespace 

Enable the Gateway API Alpha feature gate:

 kubectl set env -n kong deployment/kong-controller CONTROLLER_FEATURE_GATES="GatewayAlpha=true" -c ingress-controller

The results should look like this:

deployment.apps/kong-controller env updated

Test connectivity to Kong

Kubernetes exposes the proxy through a Kubernetes service. Run the following commands to store the load balancer IP address in a variable named PROXY_IP:

Populate $PROXY_IP for future commands:

 export PROXY_IP=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
 echo $PROXY_IP

Ensure that you can call the proxy IP:

 curl -i $PROXY_IP

The results should look like this:

 HTTP/1.1 404 Not Found
 Content-Type: application/json; charset=utf-8
 Connection: keep-alive
 Content-Length: 48
 X-Kong-Response-Latency: 0
 Server: kong/3.0.0
  
 {"message":"no Route matched with those values"}

TLS Termination

Deploy the echo service as a target for our HTTPRoutes
```
 kubectl apply -f https://docs.konghq.com/assets/kubernetes-ingress-controller/examples/echo-service.yaml
```
For TLS termination, you need to configure a Secret for listener certificate on the Gateway or for the certificate on spec.tls of the Ingress. This certificate will be used in setting up TLS connection between your client and Kong Gateway.

Create a test certificate for the demo.example.com hostname.

      OpenSSL 1.1.1
    

      OpenSSL 0.9.8
    
openssl req -subj '/CN=demo.example.com' -new -newkey rsa:2048 -sha256 \
  -days 365 -nodes -x509 -keyout server.key -out server.crt \
  -addext "subjectAltName = DNS:demo.example.com" \
  -addext "keyUsage = digitalSignature" \
  -addext "extendedKeyUsage = serverAuth" 2> /dev/null;
  openssl x509 -in server.crt -subject -noout
openssl req -subj '/CN=demo.example.com' -new -newkey rsa:2048 -sha256 \
  -days 365 -nodes -x509 -keyout server.key -out server.crt \
  -extensions EXT -config <( \
   printf "[dn]\nCN=demo.example.com\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:demo.example.com\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth") 2>/dev/null;
  openssl x509 -in server.crt -subject -noout

The results should look like this:

      OpenSSL 1.1.1
    
      OpenSSL 0.9.8
    
subject=CN = demo.example.com
subject=CN = demo.example.com

Older OpenSSL versions, including the version provided with OS X Monterey, require using the alternative version of this command.

Create a Secret containing the certificate.

 kubectl create secret tls demo.example.com --cert=./server.crt --key=./server.key

The results should look like this:

 secret/demo.example.com created

Gateway API

Ingress

Update the Gateway resource.

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

Bind an HTTPRoute to the Gateway.

 echo '
 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' | kubectl apply -f -

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

Verification

You can verify the configuration by using curl:

  curl --cacert ./server.crt -i -k -v -H "Host:demo.example.com" https://${PROXY_IP}/echo

You should get the following response:

Running on Pod example-echo-server-abcdef1-xxxxx

TLS Passthrough

For TLS passthrough, you also need to create a Secret for the TLS secret that is used for creating TLS connection between your client and the backend server.

Create a test certificate for the demo.example.com hostname.

      OpenSSL 1.1.1
    

      OpenSSL 0.9.8
    
openssl req -subj '/CN=demo.example.com' -new -newkey rsa:2048 -sha256 \
  -days 365 -nodes -x509 -keyout server.key -out server.crt \
  -addext "subjectAltName = DNS:demo.example.com" \
  -addext "keyUsage = digitalSignature" \
  -addext "extendedKeyUsage = serverAuth" 2> /dev/null;
  openssl x509 -in server.crt -subject -noout
openssl req -subj '/CN=demo.example.com' -new -newkey rsa:2048 -sha256 \
  -days 365 -nodes -x509 -keyout server.key -out server.crt \
  -extensions EXT -config <( \
   printf "[dn]\nCN=demo.example.com\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:demo.example.com\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth") 2>/dev/null;
  openssl x509 -in server.crt -subject -noout

The results should look like this:

      OpenSSL 1.1.1
    
      OpenSSL 0.9.8
    
subject=CN = demo.example.com
subject=CN = demo.example.com

Older OpenSSL versions, including the version provided with OS X Monterey, require using the alternative version of this command.

Create a Secret containing the certificate.

 kubectl create secret tls demo.example.com --cert=./server.crt --key=./server.key

The results should look like this:

 secret/demo.example.com created

Configure Kong Gateway to listen on a TLS port and enable TLSRoute in Kong Ingress Controller:

Create values-tls-passthrough.yaml:

 echo '
   gateway:
     env:
       stream_listen: "0.0.0.0:8899 ssl" # listen a TLS port
     proxy:
       stream:
       - containerPort: 8899 # configure the service to forward traffic to the TLS port
         servicePort: 8899

   controller:
     ingressController:
       env:
         feature_gates: "GatewayAlpha=true" # enable GatewayAlpha feature gate to turn on TLSRoute controller
 ' > values-tls-passthrough.yaml

Deploy Kong Ingress Controller with:
```
 helm upgrade -i kong kong/ingress -n kong --values values-tls-passthrough.yaml --create-namespace
```
Then you can create a Deployment to run a server accepting TLS connections with the certificate created previously, and a Service to expose the server:

Deploy the tlsecho service as a target for our HTTPRoutes

 kubectl apply -f https://docs.konghq.com/assets/kubernetes-ingress-controller/examples/tls-echo-service.yaml

Gateway API

Ingress

Create a Gateway resource.

 echo '
 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: example-gateway-passthrough
 spec:
   gatewayClassName: kong
   listeners:
   - name: https
     port: 8899
     protocol: TLS
     hostname: "demo.example.com"
     tls:
       mode: Passthrough ' | kubectl apply -f -

Bind a TLSRoute to the Gateway.

 echo '
 apiVersion: gateway.networking.k8s.io/v1alpha2
 kind: TLSRoute
 metadata:
   name: demo-example-passthrough
 spec:
   parentRefs:
   - name: example-gateway-passthrough
     sectionName: https
   hostnames:
   - demo.example.com
   rules:
   - backendRefs:
     - name: tlsecho
       port: 1030' | kubectl apply -f -

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.

Verification

To verify that the TLS passthrough is configured correctly (for example, by openssl’s TLS client) use the following commands:

openssl s_client -connect ${PROXY_IP}:8899 -servername demo.example.com

You should receive the following content from the connection:

Running on Pod example-tlsroute-manifest.
Through TLS connection.