Ingress Gateway without TLS Termination

The Securing Gateways with HTTPS task describes how to configure HTTPS ingress access to an HTTP service. This example describes how to configure HTTPS ingress access to an HTTPS service, i.e., configure an ingress gateway to perform SNI passthrough, instead of TLS termination on incoming requests.

The example HTTPS service used for this task is a simple NGINX server. In the following steps you first deploy the NGINX service in your Kubernetes cluster. Then you configure a gateway to provide ingress access to the service via host nginx.example.com.

Istio supports the Kubernetes Gateway API and intends to make it the default API for traffic management in the future. The following instructions allow you to choose to use either the Gateway API or the Istio configuration API when configuring traffic management in the mesh. Follow instructions under either the Gateway API or Istio APIs tab, according to your preference.

This document configures Istio using Gateway API features that are experimental Before using the Gateway API instructions, make sure to:

  1. Install the experimental version of the Gateway API CRDs:

    1. $ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.1.0" | kubectl apply -f -

  2. Configure Istio to read the alpha Gateway API resources by setting the PILOT_ENABLE_ALPHA_GATEWAY_API environment variable to true when installing Istio:

    1. $ istioctl install --set values.pilot.env.PILOT_ENABLE_ALPHA_GATEWAY_API=true --set profile=minimal -y

Before you begin

Setup Istio by following the instructions in the Installation guide.

Generate client and server certificates and keys

For this task you can use your favorite tool to generate certificates and keys. The commands below use openssl:

  1. Create a root certificate and private key to sign the certificate for your services:

    1. $ mkdir example_certs
    2. $ 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 certificate and a private key for nginx.example.com:

    1. $ 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"
    2. $ 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

Deploy an NGINX server

  1. Create a Kubernetes Secret to hold the server’s certificate.

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

  2. Create a configuration file for the NGINX server:

    1. $ cat <<\EOF > ./nginx.conf
    2. events {
    3. }
    5. http {
    6.   log_format main '$remote_addr - $remote_user [$time_local]  $status '
    7.   '"$request" $body_bytes_sent "$http_referer" '
    8.   '"$http_user_agent" "$http_x_forwarded_for"';
    9.   access_log /var/log/nginx/access.log main;
    10.   error_log  /var/log/nginx/error.log;
    12.   server {
    13.     listen 443 ssl;
    15.     root /usr/share/nginx/html;
    16.     index index.html;
    18.     server_name nginx.example.com;
    19.     ssl_certificate /etc/nginx-server-certs/tls.crt;
    20.     ssl_certificate_key /etc/nginx-server-certs/tls.key;
    21.   }
    22. }
    23. EOF

  3. Create a Kubernetes ConfigMap to hold the configuration of the NGINX server:

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

  4. Deploy the NGINX server:

    1. $ cat <<EOF | kubectl apply -f -
    2. apiVersion: v1
    3. kind: Service
    4. metadata:
    5.   name: my-nginx
    6.   labels:
    7.     run: my-nginx
    8. spec:
    9.   ports:
    10.   - port: 443
    11.     protocol: TCP
    12.   selector:
    13.     run: my-nginx
    14. ---
    15. apiVersion: apps/v1
    16. kind: Deployment
    17. metadata:
    18.   name: my-nginx
    19. spec:
    20.   selector:
    21.     matchLabels:
    22.       run: my-nginx
    23.   replicas: 1
    24.   template:
    25.     metadata:
    26.       labels:
    27.         run: my-nginx
    28.         sidecar.istio.io/inject: "true"
    29.     spec:
    30.       containers:
    31.       - name: my-nginx
    32.         image: nginx
    33.         ports:
    34.         - containerPort: 443
    35.         volumeMounts:
    36.         - name: nginx-config
    37.           mountPath: /etc/nginx
    38.           readOnly: true
    39.         - name: nginx-server-certs
    40.           mountPath: /etc/nginx-server-certs
    41.           readOnly: true
    42.       volumes:
    43.       - name: nginx-config
    44.         configMap:
    45.           name: nginx-configmap
    46.       - name: nginx-server-certs
    47.         secret:
    48.           secretName: nginx-server-certs
    49. EOF

  5. To test that the NGINX server was deployed successfully, send a request to the server from its sidecar proxy without checking the server’s certificate (use the -k option of curl). Ensure that the server’s certificate is printed correctly, i.e., common name (CN) is equal to nginx.example.com.

    1. $ kubectl exec "$(kubectl get pod  -l run=my-nginx -o jsonpath={.items..metadata.name})" -c istio-proxy -- curl -sS -v -k --resolve nginx.example.com:443:127.0.0.1 https://nginx.example.com
    2. ...
    3. SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
    4. ALPN, server accepted to use http/1.1
    5. Server certificate:
    6.   subject: CN=nginx.example.com; O=some organization
    7.   start date: May 27 14:18:47 2020 GMT
    8.   expire date: May 27 14:18:47 2021 GMT
    9.   issuer: O=example Inc.; CN=example.com
    10.   SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
    12. > GET / HTTP/1.1
    13. > User-Agent: curl/7.58.0
    14. > Host: nginx.example.com
    15. ...
    16. < HTTP/1.1 200 OK
    18. < Server: nginx/1.17.10
    19. ...
    20. <!DOCTYPE html>
    21. <html>
    22. <head>
    23. <title>Welcome to nginx!</title>
    24. ...

Configure an ingress gateway

  1. Define a Gateway exposing port 443 with passthrough TLS mode. This instructs the gateway to pass the ingress traffic “as is”, without terminating TLS:
  1. $ kubectl apply -f - <<EOF
  2. apiVersion: networking.istio.io/v1
  3. kind: Gateway
  4. metadata:
  5.   name: mygateway
  6. spec:
  7.   selector:
  8.     istio: ingressgateway # use istio default ingress gateway
  9.   servers:
  10.   - port:
  11.       number: 443
  12.       name: https
  13.       protocol: HTTPS
  14.     tls:
  15.       mode: PASSTHROUGH
  16.     hosts:
  17.     - nginx.example.com
  18. EOF
  1. $ kubectl apply -f - <<EOF
  2. apiVersion: gateway.networking.k8s.io/v1
  3. kind: Gateway
  4. metadata:
  5.   name: mygateway
  6. spec:
  7.   gatewayClassName: istio
  8.   listeners:
  9.   - name: https
  10.     hostname: "nginx.example.com"
  11.     port: 443
  12.     protocol: TLS
  13.     tls:
  14.       mode: Passthrough
  15.     allowedRoutes:
  16.       namespaces:
  17.         from: All
  18. EOF
  1. Configure routes for traffic entering via the Gateway:
  1. $ kubectl apply -f - <<EOF
  2. apiVersion: networking.istio.io/v1
  3. kind: VirtualService
  4. metadata:
  5.   name: nginx
  6. spec:
  7.   hosts:
  8.   - nginx.example.com
  9.   gateways:
  10.   - mygateway
  11.   tls:
  12.   - match:
  13.     - port: 443
  14.       sniHosts:
  15.       - nginx.example.com
  16.     route:
  17.     - destination:
  18.         host: my-nginx
  19.         port:
  20.           number: 443
  21. EOF
  1. $ kubectl apply -f - <<EOF
  2. apiVersion: gateway.networking.k8s.io/v1alpha2
  3. kind: TLSRoute
  4. metadata:
  5.   name: nginx
  6. spec:
  7.   parentRefs:
  8.   - name: mygateway
  9.   hostnames:
  10.   - "nginx.example.com"
  11.   rules:
  12.   - backendRefs:
  13.     - name: my-nginx
  14.       port: 443
  15. EOF
  1. Determine the ingress IP and port:

Follow the instructions in Determining the ingress IP and ports to set the SECURE_INGRESS_PORT and INGRESS_HOST environment variables.

Use the following commands to set the SECURE_INGRESS_PORT and INGRESS_HOST environment variables:

  1. $ kubectl wait --for=condition=programmed gtw mygateway
  2. $ export INGRESS_HOST=$(kubectl get gtw mygateway -o jsonpath='{.status.addresses[0].value}')
  3. $ export SECURE_INGRESS_PORT=$(kubectl get gtw mygateway -o jsonpath='{.spec.listeners[?(@.name=="https")].port}')

  1. Access the NGINX service from outside the cluster. Note that the correct certificate is returned by the server and it is successfully verified (SSL certificate verify ok is printed).

    1. $ curl -v --resolve "nginx.example.com:$SECURE_INGRESS_PORT:$INGRESS_HOST" --cacert example_certs/example.com.crt "https://nginx.example.com:$SECURE_INGRESS_PORT"
    2. Server certificate:
    3.   subject: CN=nginx.example.com; O=some organization
    4.   start date: Wed, 15 Aug 2018 07:29:07 GMT
    5.   expire date: Sun, 25 Aug 2019 07:29:07 GMT
    6.   issuer: O=example Inc.; CN=example.com
    7.   SSL certificate verify ok.
    9.   < HTTP/1.1 200 OK
    10.   < Server: nginx/1.15.2
    11.   ...
    12.   <html>
    13.   <head>
    14.   <title>Welcome to nginx!</title>

Cleanup

  1. Delete the gateway configuration and route:
  1. $ kubectl delete gateway mygateway
  2. $ kubectl delete virtualservice nginx
  1. $ kubectl delete gtw mygateway
  2. $ kubectl delete tlsroute nginx

  1. Remove the NGINX resources and configuration file:

    1. $ kubectl delete secret nginx-server-certs
    2. $ kubectl delete configmap nginx-configmap
    3. $ kubectl delete service my-nginx
    4. $ kubectl delete deployment my-nginx
    5. $ rm ./nginx.conf

  2. Delete the certificates and keys:

    1. $ rm -rf ./example_certs