Mutual TLS Migration

This task shows how to ensure your workloads only communicate using mutual TLS as they are migrated to Istio.

Istio automatically configures workload sidecars to use mutual TLS when calling other workloads. By default, Istio configures the destination workloads using PERMISSIVE mode. When PERMISSIVE mode is enabled, a service can accept both plain text and mutual TLS traffic. In order to only allow mutual TLS traffic, the configuration needs to be changed to STRICT mode.

You can use the Grafana dashboard to check which workloads are still sending plaintext traffic to the workloads in PERMISSIVE mode and choose to lock them down once the migration is done.

Before you begin

In this task, you can try out the migration process by creating sample workloads and modifying the policies to enforce STRICT mutual TLS between the workloads.

Set up the cluster

  • Create two namespaces, foo and bar, and deploy httpbin and sleep with sidecars on both of them:

    ZipZipZipZip

    1. $ kubectl create ns foo
    2. $ kubectl apply -f <(istioctl kube-inject -f @samples/httpbin/httpbin.yaml@) -n foo
    3. $ kubectl apply -f <(istioctl kube-inject -f @samples/sleep/sleep.yaml@) -n foo
    4. $ kubectl create ns bar
    5. $ kubectl apply -f <(istioctl kube-inject -f @samples/httpbin/httpbin.yaml@) -n bar
    6. $ kubectl apply -f <(istioctl kube-inject -f @samples/sleep/sleep.yaml@) -n bar
  • Create another namespace, legacy, and deploy sleep without a sidecar:

    Zip

    1. $ kubectl create ns legacy
    2. $ kubectl apply -f @samples/sleep/sleep.yaml@ -n legacy
  • Verify the setup by sending http requests (using curl) from the sleep pods, in namespaces foo, bar and legacy, to httpbin.foo and httpbin.bar. All requests should succeed with return code 200.

    1. $ for from in "foo" "bar" "legacy"; do for to in "foo" "bar"; do kubectl exec "$(kubectl get pod -l app=sleep -n ${from} -o jsonpath={.items..metadata.name})" -c sleep -n ${from} -- curl http://httpbin.${to}:8000/ip -s -o /dev/null -w "sleep.${from} to httpbin.${to}: %{http_code}\n"; done; done
    2. sleep.foo to httpbin.foo: 200
    3. sleep.foo to httpbin.bar: 200
    4. sleep.bar to httpbin.foo: 200
    5. sleep.bar to httpbin.bar: 200
    6. sleep.legacy to httpbin.foo: 200
    7. sleep.legacy to httpbin.bar: 200

    If any of the curl commands fail, ensure that there are no existing authentication policies or destination rules that might interfere with requests to the httpbin service.

    1. $ kubectl get peerauthentication --all-namespaces
    2. No resources found.
    1. $ kubectl get destinationrule --all-namespaces
    2. No resources found.

Lock down to mutual TLS by namespace

After migrating all clients to Istio and injecting the Envoy sidecar, you can lock down workloads in the foo namespace to only accept mutual TLS traffic.

  1. $ kubectl apply -n foo -f - <<EOF
  2. apiVersion: "security.istio.io/v1beta1"
  3. kind: "PeerAuthentication"
  4. metadata:
  5. name: "default"
  6. spec:
  7. mtls:
  8. mode: STRICT
  9. EOF

Now, you should see the request from sleep.legacy to httpbin.foo failing.

  1. $ for from in "foo" "bar" "legacy"; do for to in "foo" "bar"; do kubectl exec "$(kubectl get pod -l app=sleep -n ${from} -o jsonpath={.items..metadata.name})" -c sleep -n ${from} -- curl http://httpbin.${to}:8000/ip -s -o /dev/null -w "sleep.${from} to httpbin.${to}: %{http_code}\n"; done; done
  2. sleep.foo to httpbin.foo: 200
  3. sleep.foo to httpbin.bar: 200
  4. sleep.bar to httpbin.foo: 200
  5. sleep.bar to httpbin.bar: 200
  6. sleep.legacy to httpbin.foo: 000
  7. command terminated with exit code 56
  8. sleep.legacy to httpbin.bar: 200

If you installed Istio with values.global.proxy.privileged=true, you can use tcpdump to verify traffic is encrypted or not.

  1. $ kubectl exec -nfoo "$(kubectl get pod -nfoo -lapp=httpbin -ojsonpath={.items..metadata.name})" -c istio-proxy -- sudo tcpdump dst port 80 -A
  2. tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
  3. listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes

You will see plain text and encrypted text in the output when requests are sent from sleep.legacy and sleep.foo respectively.

If you can’t migrate all your services to Istio (i.e., inject Envoy sidecar in all of them), you will need to continue to use PERMISSIVE mode. However, when configured with PERMISSIVE mode, no authentication or authorization checks will be performed for plaintext traffic by default. We recommend you use Istio Authorization to configure different paths with different authorization policies.

Lock down mutual TLS for the entire mesh

  1. $ kubectl apply -n istio-system -f - <<EOF
  2. apiVersion: "security.istio.io/v1beta1"
  3. kind: "PeerAuthentication"
  4. metadata:
  5. name: "default"
  6. spec:
  7. mtls:
  8. mode: STRICT
  9. EOF

Now, both the foo and bar namespaces enforce mutual TLS only traffic, so you should see requests from sleep.legacy failing for both.

  1. $ for from in "foo" "bar" "legacy"; do for to in "foo" "bar"; do kubectl exec "$(kubectl get pod -l app=sleep -n ${from} -o jsonpath={.items..metadata.name})" -c sleep -n ${from} -- curl http://httpbin.${to}:8000/ip -s -o /dev/null -w "sleep.${from} to httpbin.${to}: %{http_code}\n"; done; done

Clean up the example

  1. Remove the mesh-wide authentication policy.
  1. $ kubectl delete peerauthentication -n istio-system default
  1. Remove the test namespaces.
  1. $ kubectl delete ns foo bar legacy
  2. Namespaces foo bar legacy deleted.

See also

Authentication Policy

Shows you how to use Istio authentication policy to setup mutual TLS and basic end-user authentication.

Authorization Policy Trust Domain Migration

Shows how to migrate from one trust domain to another without changing authorization policy.

Security

Describes Istio’s authorization and authentication functionality.

Migrate pre-Istio 1.4 Alpha security policy to the current APIs

A tutorial to help customers migrate from the deprecated v1alpha1 security policy to the supported v1beta1 version.

Introducing Workload Entries

Describing the new functionality of Workload Entries.

Istio in 2020 - Following the Trade Winds

A vision statement and roadmap for Istio in 2020.