TLS passthrough

Set up a TLS listener on the Gateway that serves one or more hosts and passes TLS traffic through to a destination. Because TLS traffic is not terminated at the Gateway, the destination must be capable of handling incoming TLS traffic.

Before you begin

1. Set up kgateway by following the Quick start or Installation guides.

2. Deploy the httpbin sample app.

3. Make sure that you have the OpenSSL version of openssl, not LibreSSL. The openssl version must be at least 1.1.

   1. Check the openssl version that is installed. If you see LibreSSL in the output, continue to the next step.

      openssl version

   2. Install the OpenSSL version (not LibreSSL). For example, you might use Homebrew.

      brew install openssl

   3. Review the output of the OpenSSL installation for the path of the binary file. You can choose to export the binary to your path, or call the entire path whenever the following steps use an openssl command.

      • For example, openssl might be installed along the following path: /usr/local/opt/openssl@3/bin/
      • To run commands, you can append the path so that your terminal uses this installed version of OpenSSL, and not the default LibreSSL. /usr/local/opt/openssl@3/bin/openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650...
4. Decide whether to set up a listener inline on the Gateway resource or as a separate ListenerSet resource. For more information, see the Listener overview.

   ListenerSets: This feature is available in kgateway version 2.1.x or later. Also, you must install the experimental channel of the Kubernetes Gateway API at version 1.3 or later.

Deploy an nginx server that is configured for HTTPS traffic

Deploy a sample nginx server and configure the server for HTTPS traffic.

1. Create a root certificate for the example.com domain. You use this certificate to sign the certificate for your nginx service later.

   mkdir example_certs
   openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example_certs/example.com.key -out example_certs/example.com.crt

2. Create a server certificate and private key for the nginx.example.com domain.

   openssl req -out example_certs/nginx.example.com.csr -newkey rsa:2048 -nodes -keyout example_certs/nginx.example.com.key -subj "/CN=nginx.example.com/O=some organization"
   openssl x509 -req -sha256 -days 365 -CA example_certs/example.com.crt -CAkey example_certs/example.com.key -set_serial 0 -in example_certs/nginx.example.com.csr -out example_certs/nginx.example.com.crt

3. Create a secret that stores the certificate and key for the nginx server.

   kubectl create secret tls nginx-server-certs \
    --key example_certs/nginx.example.com.key \
    --cert example_certs/nginx.example.com.crt

4. Prepare your nginx configuration. The following example configures nginx for HTTPS traffic with the certificate that you created earlier.

   cat <<\EOF > ./nginx.conf
   events {
   }
   
   http {
     log_format main '$remote_addr - $remote_user [$time_local]  $status '
     '"$request" $body_bytes_sent "$http_referer" '
     '"$http_user_agent" "$http_x_forwarded_for"';
     access_log /var/log/nginx/access.log main;
     error_log  /var/log/nginx/error.log;
   
     server {
       listen 443 ssl;
   
       root /usr/share/nginx/html;
       index index.html;
   
       server_name nginx.example.com;
       ssl_certificate /etc/nginx-server-certs/tls.crt;
       ssl_certificate_key /etc/nginx-server-certs/tls.key;
     }
   }
   EOF

5. Store the nginx configuration in a configmap.

   kubectl create configmap nginx-configmap --from-file=nginx.conf=./nginx.conf

6. Deploy the nginx server.

   kubectl apply -f- <<EOF
   apiVersion: v1
   kind: Service
   metadata:
     name: my-nginx
     labels:
       run: my-nginx
   spec:
     ports:
     - port: 443
       protocol: TCP
     selector:
       run: my-nginx
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: my-nginx
   spec:
     selector:
       matchLabels:
         run: my-nginx
     replicas: 1
     template:
       metadata:
         labels:
           run: my-nginx
       spec:
         containers:
         - name: my-nginx
           image: nginx
           ports:
           - containerPort: 443
           volumeMounts:
           - name: nginx-config
             mountPath: /etc/nginx
             readOnly: true
           - name: nginx-server-certs
             mountPath: /etc/nginx-server-certs
             readOnly: true
         volumes:
         - name: nginx-config
           configMap:
             name: nginx-configmap
         - name: nginx-server-certs
           secret:
             secretName: nginx-server-certs
   EOF

7. Verify that the server is up and running.

   kubectl get pods | grep nginx

   Example output:

   my-nginx-c4c49df8f-2bkws    1/1     Running   0          34s

Set up TLS passthrough

To route TLS traffic to the nginx server directly without terminating the TLS connection at the Gateway, you can use either an inline Gateway listener or a ListenerSet. Then, you create a TLSRoute that represents the route to your nginx server and attach it to the Gateway or ListenerSet.

If you plan to set up your listener as part of a ListenerSet, keep the following considerations in mind. For more information, see ListenerSets (experimental).

• This feature is available in kgateway version 2.1.x or later.
• You must install the experimental channel of the Kubernetes Gateway API at version 1.3 or later.

Create a TLSRoute

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: tlsroute
  namespace: default
spec:
  parentRefs:
    - name: tls-passthrough
      namespace: kgateway-system
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: my-nginx
          port: 443
EOF

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: tlsroute
  namespace: default
spec:
  parentRefs:
    - name: my-tls-listenerset
      namespace: kgateway-system
      kind: XListenerSet
      group: gateway.networking.x-k8s.io
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: my-nginx
          port: 443
EOF

Verify TLS passthrough traffic for nginx

Cleanup

rm -r example_certs
rm nginx.conf
kubectl delete configmap nginx-configmap
kubectl delete tlsroute tlsroute
kubectl delete gateway tls-passthrough -n kgateway-system
kubectl delete deployment my-nginx
kubectl delete service my-nginx
kubectl delete secret nginx-server-certs   

rm -r example_certs
rm nginx.conf
kubectl delete configmap nginx-configmap
kubectl delete tlsroute tlsroute
kubectl delete XListenerSet my-tls-listenerset -n kgateway-system
kubectl delete gateway tls-passthrough -n kgateway-system
kubectl delete deployment my-nginx
kubectl delete service my-nginx
kubectl delete secret nginx-server-certs