Egress Gateways with TLS Origination (SDS)

    The TLS required private key, server certificate, and root certificate, are configured using the .

    • Setup Istio by following the instructions in the Installation guide.

    • Start the sample which will be used as a test source for external calls.

      If you have enabled automatic sidecar injection, do

      otherwise, you have to manually inject the sidecar before deploying the application:

      Zip

      1. $ kubectl apply -f <(istioctl kube-inject -f @samples/sleep/sleep.yaml@)

      Note that any pod that you can exec and curl from would do.

    • For macOS users, verify that you are using openssl version 1.1 or later:

      1. $ openssl version -a | grep OpenSSL
      2. OpenSSL 1.1.1g  21 Apr 2020

      If the previous command outputs a version 1.1 or later, as shown, your openssl command should work correctly with the instructions in this task. Otherwise, upgrade your openssl or try a different implementation of openssl, for example on a Linux machine.

    • .

    • Enable Envoy’s access logging.

    If you configured an egress gateway using the , and you want to migrate your egress gateway to use the SDS approach, there are no extra steps required.

    This section describes how to perform the same TLS origination as in the TLS Origination for Egress Traffic example, only this time using an egress gateway. Note that in this case the TLS origination will be done by the egress gateway, as opposed to by the sidecar in the previous example. The egress gateway will use SDS instead of the file-mount to provision client certificates.

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

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

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

    2. Create a certificate and a private key for my-nginx.mesh-external.svc.cluster.local:

      1. $ openssl req -out my-nginx.mesh-external.svc.cluster.local.csr -newkey rsa:2048 -nodes -keyout my-nginx.mesh-external.svc.cluster.local.key -subj "/CN=my-nginx.mesh-external.svc.cluster.local/O=some organization"
      2. $ openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in my-nginx.mesh-external.svc.cluster.local.csr -out my-nginx.mesh-external.svc.cluster.local.crt

    Deploy a simple TLS server

    To simulate an actual external service that supports the simple TLS protocol, deploy an NGINX server in your Kubernetes cluster, but running outside of the Istio service mesh, i.e., in a namespace without Istio sidecar proxy injection enabled.

    1. Create a namespace to represent services outside the Istio mesh, namely mesh-external. Note that the sidecar proxy will not be automatically injected into the pods in this namespace since the automatic sidecar injection was not on it.

      1. $ kubectl create namespace mesh-external

    2. Create Kubernetes Secrets to hold the server’s and CA certificates.

      1. $ kubectl create -n mesh-external secret tls nginx-server-certs --key my-nginx.mesh-external.svc.cluster.local.key --cert my-nginx.mesh-external.svc.cluster.local.crt
      2. $ kubectl create -n mesh-external secret generic nginx-ca-certs --from-file=example.com.crt
      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 my-nginx.mesh-external.svc.cluster.local;
      19.     ssl_certificate /etc/nginx-server-certs/tls.crt;
      20.     ssl_certificate_key /etc/nginx-server-certs/tls.key;
      21.     ssl_client_certificate /etc/nginx-ca-certs/example.com.crt;
      22.     ssl_verify_client off; # In simple TLS, server doesn't verify client's certificate
      23.   }
      24. }
      25. EOF

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

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

    5. Deploy the NGINX server:

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

    1. Create a Kubernetes Secret to hold the CA certificate used by egress gateway to originate TLS connections:

      1. $ kubectl create secret generic client-credential-cacert --from-file=ca.crt=example.com.crt -n istio-system

      Note that the secret name for an Istio CA-only certificate must end with -cacert and the secret must be created in the same namespace as Istio is deployed in, istio-system in this case.

      The secret name should not begin with istio or prometheus, and the secret should not contain a token field.

    2. Create an egress Gateway for my-nginx.mesh-external.svc.cluster.local, port 443, and destination rules and virtual services to direct the traffic through the egress gateway and from the egress gateway to the external service.

      1. $ kubectl apply -f - <<EOF
      2. apiVersion: networking.istio.io/v1alpha3
      3. kind: Gateway
      4. metadata:
      5.   name: istio-egressgateway
      6. spec:
      7.   selector:
      8.     istio: egressgateway
      9.   servers:
      10.   - port:
      11.       number: 443
      12.       name: https
      13.       protocol: HTTPS
      14.     hosts:
      15.     - my-nginx.mesh-external.svc.cluster.local
      16.     tls:
      17.       mode: ISTIO_MUTUAL
      18. ---
      19. apiVersion: networking.istio.io/v1alpha3
      20. kind: DestinationRule
      21. metadata:
      22.   name: egressgateway-for-nginx
      23. spec:
      24.   host: istio-egressgateway.istio-system.svc.cluster.local
      25.   subsets:
      26.   - name: nginx
      27.       loadBalancer:
      28.         simple: ROUND_ROBIN
      29.       portLevelSettings:
      30.       - port:
      31.           number: 443
      33.           mode: ISTIO_MUTUAL
      34.           sni: my-nginx.mesh-external.svc.cluster.local
      35. EOF

    3. Define a VirtualService to direct the traffic through the egress gateway:

      1. $ kubectl apply -f - <<EOF
      2. apiVersion: networking.istio.io/v1alpha3
      3. kind: VirtualService
      4. metadata:
      5.   name: direct-nginx-through-egress-gateway
      6. spec:
      7.   hosts:
      8.   - my-nginx.mesh-external.svc.cluster.local
      9.   gateways:
      10.   - istio-egressgateway
      11.   - mesh
      12.   http:
      13.   - match:
      14.     - gateways:
      15.       - mesh
      16.       port: 80
      17.     route:
      18.     - destination:
      19.         host: istio-egressgateway.istio-system.svc.cluster.local
      20.         subset: nginx
      21.         port:
      22.           number: 443
      23.       weight: 100
      24.   - match:
      25.     - gateways:
      26.       - istio-egressgateway
      27.       port: 443
      28.     route:
      29.     - destination:
      30.         host: my-nginx.mesh-external.svc.cluster.local
      31.         port:
      32.           number: 443
      33.       weight: 100
      34. EOF

    4. Add a DestinationRule to perform simple TLS origination

    5. Send an HTTP request to http://my-nginx.mesh-external.svc.cluster.local:

      1. $ kubectl exec "$(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name})" -c sleep -- curl -sS http://my-nginx.mesh-external.svc.cluster.local
      2. <!DOCTYPE html>
      3. <html>
      4. <head>
      5. <title>Welcome to nginx!</title>
      6. ...

    6. Check the log of the istio-egressgateway pod for a line corresponding to our request. If Istio is deployed in the istio-system namespace, the command to print the log is:

      1. $ kubectl logs -l istio=egressgateway -n istio-system | grep 'my-nginx.mesh-external.svc.cluster.local' | grep HTTP

      You should see a line similar to the following:

      1. [2018-08-19T18:20:40.096Z] "GET / HTTP/1.1" 200 - 0 612 7 5 "172.30.146.114" "curl/7.35.0" "b942b587-fac2-9756-8ec6-303561356204" "my-nginx.mesh-external.svc.cluster.local" "172.21.72.197:443"

    Cleanup the TLS origination example

    1. Remove the Istio configuration items you created:

      1. $ kubectl delete destinationrule originate-tls-for-nginx -n istio-system
      2. $ kubectl delete virtualservice direct-nginx-through-egress-gateway
      3. $ kubectl delete destinationrule egressgateway-for-nginx
      4. $ kubectl delete gateway istio-egressgateway
      5. $ kubectl delete secret client-credential-cacert -n istio-system
      6. $ kubectl delete service my-nginx -n mesh-external
      7. $ kubectl delete deployment my-nginx -n mesh-external
      8. $ kubectl delete configmap nginx-configmap -n mesh-external
      9. $ kubectl delete secret nginx-server-certs nginx-ca-certs -n mesh-external
      10. $ kubectl delete namespace mesh-external

    2. Delete the certificates and private keys:

      1. $ rm example.com.crt example.com.key my-nginx.mesh-external.svc.cluster.local.crt my-nginx.mesh-external.svc.cluster.local.key my-nginx.mesh-external.svc.cluster.local.csr

    3. Delete the generated configuration files used in this example:

      1. $ rm ./nginx.conf

    Similar to the previous section, this section describes how to configure an egress gateway to perform TLS origination for an external service, only this time using a service that requires mutual TLS.

    Egress Gateway will use SDS instead of the file-mount to provision client certificates.

    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. $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -subj '/O=example Inc./CN=example.com' -keyout example.com.key -out example.com.crt

    2. Create a certificate and a private key for my-nginx.mesh-external.svc.cluster.local:

      1. $ openssl req -out my-nginx.mesh-external.svc.cluster.local.csr -newkey rsa:2048 -nodes -keyout my-nginx.mesh-external.svc.cluster.local.key -subj "/CN=my-nginx.mesh-external.svc.cluster.local/O=some organization"
      2. $ openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 0 -in my-nginx.mesh-external.svc.cluster.local.csr -out my-nginx.mesh-external.svc.cluster.local.crt

    3. Generate client certificate and private key:

      1. $ openssl req -out client.example.com.csr -newkey rsa:2048 -nodes -keyout client.example.com.key -subj "/CN=client.example.com/O=client organization"
      2. $ openssl x509 -req -days 365 -CA example.com.crt -CAkey example.com.key -set_serial 1 -in client.example.com.csr -out client.example.com.crt

    Deploy a mutual TLS server

    1. Create a namespace to represent services outside the Istio mesh, namely mesh-external. Note that the sidecar proxy will not be automatically injected into the pods in this namespace since the automatic sidecar injection was not on it.

      1. $ kubectl create namespace mesh-external

    2. Create Kubernetes Secrets to hold the server’s certificates.

      1. $ kubectl create -n mesh-external secret tls nginx-server-certs --key my-nginx.mesh-external.svc.cluster.local.key --cert my-nginx.mesh-external.svc.cluster.local.crt
      2. $ kubectl create -n mesh-external secret generic nginx-ca-certs --from-file=example.com.crt

    3. 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 my-nginx.mesh-external.svc.cluster.local;
      19.     ssl_certificate /etc/nginx-server-certs/tls.crt;
      20.     ssl_certificate_key /etc/nginx-server-certs/tls.key;
      21.     ssl_client_certificate /etc/nginx-ca-certs/example.com.crt;
      22.     ssl_verify_client on; # In mutual TLS, server verifies client's certificate
      23.   }
      24. }
      25. EOF

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

    5. Deploy the NGINX server:

      1. $ kubectl apply -f - <<EOF
      2. apiVersion: v1
      3. kind: Service
      4. metadata:
      5.   name: my-nginx
      6.   namespace: mesh-external
      7.   labels:
      8.     run: my-nginx
      9. spec:
      10.   ports:
      11.   - port: 443
      12.     protocol: TCP
      13.   selector:
      14.     run: my-nginx
      15. ---
      16. apiVersion: apps/v1
      17. kind: Deployment
      18. metadata:
      19.   name: my-nginx
      20.   namespace: mesh-external
      21. spec:
      22.   selector:
      23.     matchLabels:
      24.       run: my-nginx
      25.   replicas: 1
      26.   template:
      27.     metadata:
      28.       labels:
      29.         run: my-nginx
      30.     spec:
      31.       containers:
      32.       - name: my-nginx
      33.         image: nginx
      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.         - name: nginx-ca-certs
      44.           readOnly: true
      45.       volumes:
      46.       - name: nginx-config
      47.         configMap:
      48.           name: nginx-configmap
      49.       - name: nginx-server-certs
      50.         secret:
      51.           secretName: nginx-server-certs
      52.       - name: nginx-ca-certs
      53.         secret:
      54.           secretName: nginx-ca-certs
      55. EOF

    1. Create Kubernetes Secrets to hold the client’s certificates:

      1. $ kubectl create secret -n istio-system generic client-credential --from-file=tls.key=client.example.com.key \
      2.   --from-file=tls.crt=client.example.com.crt --from-file=ca.crt=example.com.crt

      The secret must be created in the same namespace as Istio is deployed in, istio-system in this case.

      To support integration with various tools, Istio supports a few different Secret formats.

      In this example. a single generic Secret with keys tls.key, tls.crt, and ca.crt is used.

      The secret name should not begin with istio or prometheus, and the secret should not contain a token field.

    2. Create an egress Gateway for my-nginx.mesh-external.svc.cluster.local, port 443, and destination rules and virtual services to direct the traffic through the egress gateway and from the egress gateway to the external service.

      1. $ kubectl apply -f - <<EOF
      2. apiVersion: networking.istio.io/v1alpha3
      3. kind: Gateway
      4. metadata:
      5.   name: istio-egressgateway
      6. spec:
      7.   selector:
      8.     istio: egressgateway
      9.   servers:
      10.   - port:
      11.       number: 443
      12.       name: https
      13.       protocol: HTTPS
      14.     hosts:
      15.     - my-nginx.mesh-external.svc.cluster.local
      16.     tls:
      17.       mode: ISTIO_MUTUAL
      18. ---
      19. apiVersion: networking.istio.io/v1alpha3
      20. kind: DestinationRule
      21. metadata:
      22.   name: egressgateway-for-nginx
      23. spec:
      24.   host: istio-egressgateway.istio-system.svc.cluster.local
      25.   subsets:
      26.   - name: nginx
      27.     trafficPolicy:
      28.       loadBalancer:
      29.         simple: ROUND_ROBIN
      30.       portLevelSettings:
      31.       - port:
      32.           number: 443
      33.         tls:
      34.           mode: ISTIO_MUTUAL
      35.           sni: my-nginx.mesh-external.svc.cluster.local
      36. EOF

    3. Define a VirtualService to direct the traffic through the egress gateway:

      1. $ kubectl apply -f - <<EOF
      2. apiVersion: networking.istio.io/v1alpha3
      3. kind: VirtualService
      4. metadata:
      5.   name: direct-nginx-through-egress-gateway
      6. spec:
      7.   hosts:
      8.   - my-nginx.mesh-external.svc.cluster.local
      9.   gateways:
      10.   - istio-egressgateway
      11.   - mesh
      12.   http:
      13.   - match:
      14.     - gateways:
      15.       - mesh
      16.       port: 80
      17.     route:
      18.     - destination:
      19.         host: istio-egressgateway.istio-system.svc.cluster.local
      20.         subset: nginx
      21.         port:
      22.           number: 443
      23.       weight: 100
      24.   - match:
      25.     - gateways:
      26.       - istio-egressgateway
      27.       port: 443
      28.     route:
      29.     - destination:
      30.         host: my-nginx.mesh-external.svc.cluster.local
      31.         port:
      32.           number: 443
      33.       weight: 100
      34. EOF

    4. Add a DestinationRule to perform mutual TLS origination

      1. $ kubectl apply -n istio-system -f - <<EOF
      2. apiVersion: networking.istio.io/v1alpha3
      3. kind: DestinationRule
      4. metadata:
      5.   name: originate-mtls-for-nginx
      6. spec:
      7.   host: my-nginx.mesh-external.svc.cluster.local
      8.   trafficPolicy:
      9.     loadBalancer:
      10.       simple: ROUND_ROBIN
      11.     portLevelSettings:
      12.     - port:
      13.         number: 443
      14.       tls:
      15.         mode: MUTUAL
      16.         credentialName: client-credential # this must match the secret created earlier to hold client certs
      17.         sni: my-nginx.mesh-external.svc.cluster.local
      18. EOF

    5. Send an HTTP request to http://my-nginx.mesh-external.svc.cluster.local:

      1. $ kubectl exec "$(kubectl get pod -l app=sleep -o jsonpath={.items..metadata.name})" -c sleep -- curl -sS http://my-nginx.mesh-external.svc.cluster.local
      2. <!DOCTYPE html>
      3. <html>
      4. <head>
      5. <title>Welcome to nginx!</title>
      6. ...

    6. Check the log of the istio-egressgateway pod for a line corresponding to our request. If Istio is deployed in the istio-system namespace, the command to print the log is:

      1. $ kubectl logs -l istio=egressgateway -n istio-system | grep 'my-nginx.mesh-external.svc.cluster.local' | grep HTTP

      You should see a line similar to the following:

      1. [2018-08-19T18:20:40.096Z] "GET / HTTP/1.1" 200 - 0 612 7 5 "172.30.146.114" "curl/7.35.0" "b942b587-fac2-9756-8ec6-303561356204" "my-nginx.mesh-external.svc.cluster.local" "172.21.72.197:443"

    Cleanup the mutual TLS origination example

    1. Remove created Kubernetes resources:

      1. $ kubectl delete secret nginx-server-certs nginx-ca-certs -n mesh-external
      2. $ kubectl delete secret client-credential -n istio-system
      3. $ kubectl delete configmap nginx-configmap -n mesh-external
      4. $ kubectl delete service my-nginx -n mesh-external
      5. $ kubectl delete deployment my-nginx -n mesh-external
      6. $ kubectl delete namespace mesh-external
      7. $ kubectl delete gateway istio-egressgateway
      8. $ kubectl delete virtualservice direct-nginx-through-egress-gateway
      9. $ kubectl delete destinationrule -n istio-system originate-mtls-for-nginx
      10. $ kubectl delete destinationrule egressgateway-for-nginx

    2. Delete the certificates and private keys:

      1. $ rm example.com.crt example.com.key my-nginx.mesh-external.svc.cluster.local.crt my-nginx.mesh-external.svc.cluster.local.key my-nginx.mesh-external.svc.cluster.local.csr client.example.com.crt client.example.com.csr client.example.com.key

    3. Delete the generated configuration files used in this example:

      1. $ rm ./nginx.conf
      2. $ rm ./gateway-patch.json

    Delete the sleep service and deployment:

    1. $ kubectl delete service sleep
    2. $ kubectl delete deployment sleep