Demo Authentication

In this lesson you’ll configure authentication in Istio, deploy a simple hello-world app, observe how PeerAuthentication enforces mTLS, and learn how to override global policies at namespace or workload scope. Prerequisites: kubectl and istioctl configured to talk to your cluster.

Ensure your cluster has Istio installed and the istio-system namespace is present. Use istioctl version and kubectl get ns to validate installation before proceeding.

1) Verify Istio automatic sidecar injection on namespaces

Check namespace labels to determine whether automatic Envoy sidecar injection is enabled:

kubectl get ns --show-labels

Example output:

NAME            STATUS   AGE   LABELS
default         Active   3m   istio-injection=enabled,kubernetes.io/metadata.name=default
istio-system    Active   91s  kubernetes.io/metadata.name=istio-system
kube-system     Active   3m   kubernetes.io/metadata.name=kube-system
test            Active   6m   istio-injection=enabled,kubernetes.io/metadata.name=test

The label istio-injection=enabled means pods created in that namespace get the Envoy sidecar injected automatically. If a namespace has no such label, pods will not be injected and won’t participate in mTLS unless manually proxied.

2) Deploy the helloworld sample

Apply the sample manifest to create the hello-world service and workloads:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/refs/heads/master/samples/helloworld/helloworld.yaml

Verify pods are created and ready:

kubectl get pods -l app=helloworld

Example ready state:

NAME                            READY   STATUS    RESTARTS   AGE
helloworld-v1-7459d7b54b-f7cxb  2/2     Running   0          2m
helloworld-v2-654d97458-r84kp   2/2     Running   0          2m

Note: 2/2 indicates the application container plus the Envoy sidecar are running.

3) Create a test namespace and run a client pod

Create a namespace test (if it doesn’t already exist) and run an nginx pod to act as a client:

kubectl create ns test
kubectl run test --image=nginx -n test
kubectl get pods -n test

If you accidentally created the test pod in the default namespace, delete and recreate it in test:

kubectl delete pod test
kubectl run test --image=nginx -n test

4) Verify connectivity from the test pod to helloworld

From the test pod, curl the hello endpoint on the helloworld service in the default namespace:

kubectl exec -ti -n test test -- curl helloworld.default.svc:5000/hello

You should receive a response similar to:

Hello version: v2, instance: helloworld-v2-654d97458-r84kp

Why this works: by default, Istio does not enforce mTLS cluster-wide — plaintext traffic is still allowed unless you enable enforcement via PeerAuthentication.

5) Enforce global mTLS with a PeerAuthentication

Create a global PeerAuthentication resource in istio-system to enforce strict mTLS cluster-wide. peer_auth_global.yaml

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system
spec:
  mtls:
    mode: STRICT

Apply it:

kubectl apply -f peer_auth_global.yaml

Confirm the PeerAuthentication exists:

kubectl get peerauthentications.security.istio.io -A

Example output:

NAMESPACE      NAME      MODE     AGE
istio-system   default   STRICT   10s

Now retry the curl from the non-injected test pod (if test is not injection-enabled):

kubectl exec -ti -n test test -- curl --head helloworld.default.svc:5000/hello

You will likely see a failure like:

curl: (56) Recv failure: Connection reset by peer
command terminated with exit code 56

Explanation: the server requires mTLS (STRICT). Because the test pod lacks an Envoy sidecar, the client sends plaintext traffic which the server rejects.

6) Enable injection for `test` namespace and retry

Use istioctl analyze to surface issues and then enable injection:

istioctl analyze -n test
kubectl label namespace test istio-injection=enabled

Recreate the client pod so it gets injected:

kubectl delete pod test -n test
kubectl run test --image=nginx -n test
kubectl get pods -n test

Now retry the curl (from the injected client):

kubectl exec -ti -n test test -- curl --head helloworld.default.svc:5000/hello

Expected response headers:

HTTP/1.1 200 OK
server: envoy
date: Tue, 15 Apr 2025 18:12:06 GMT
content-type: text/html; charset=utf-8
content-length: 60
x-envoy-upstream-service-time: 122

Both client and server traffic are now proxied through Envoy and use mTLS, so the connection succeeds.

7) Override global policy at namespace scope (PERMISSIVE)

A PeerAuthentication in istio-system sets a global default but can be overridden by PeerAuthentication resources in namespaces. To allow plaintext and mTLS traffic in the default namespace, create a PERMISSIVE PeerAuthentication: peer_auth_default.yaml

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: default
spec:
  mtls:
    mode: PERMISSIVE

Apply it:

kubectl apply -f peer_auth_default.yaml
kubectl get peerauthentications.security.istio.io -A

Example output:

NAMESPACE     NAME      MODE        AGE
default       default   PERMISSIVE  6s
istio-system  default   STRICT      3m7s

With PERMISSIVE in default, clients that are not mTLS-capable (non-injected) can still reach workloads in default using plaintext.

8) Target permissive mode to specific workloads (selector)

Instead of making an entire namespace permissive, scope the permissive mode to only the workloads that match labels (e.g., app=helloworld): peer_auth_default.yaml

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: default
spec:
  selector:
    matchLabels:
      app: helloworld
  mtls:
    mode: PERMISSIVE

Apply the change:

kubectl apply -f peer_auth_default.yaml
kubectl get peerauthentications.security.istio.io -A

Now PERMISSIVE applies only to pods in default that have app=helloworld. Other workloads in default remain governed by the global STRICT policy in istio-system.

Test with an `app` namespace (non-injected)

Create a non-injected app namespace and run an nginx pod:

kubectl create ns app
kubectl run test --image=nginx -n app
kubectl get pods -n app

From the non-injected app pod, curl the helloworld endpoint:

kubectl exec -ti -n app test -- curl --head helloworld.default.svc:5000/hello

Expected (permissive applies to helloworld):

HTTP/1.1 200 OK
server: istio-envoy
date: Tue, 15 Apr 2025 18:14:44 GMT
content-type: text/html; charset=utf-8
content-length: 60
x-envoy-upstream-service-time: 136
x-envoy-decorator-operation: helloworld.default.svc.cluster.local:5000/*

Now try productpage (Bookinfo) in default from the same non-injected app pod. Because the selector only matched app=helloworld, productpage is still subject to global STRICT and will reject plaintext:

kubectl exec -ti -n app test -- curl --head productpage.default.svc:9080

You should see:

curl: (56) Recv failure: Connection reset by peer
command terminated with exit code 56

The same request from an injected namespace (e.g., test) will succeed:

kubectl exec -ti -n test test -- curl --head productpage.default.svc:9080

Expected success:

HTTP/1.1 200 OK
content-type: text/html; charset=utf-8
content-length: 1683
server: envoy
date: Tue, 15 Apr 2025 18:19:47 GMT
x-envoy-upstream-service-time: 4

Summary: a global STRICT enforces mTLS cluster-wide. PeerAuthentication resources scoped to a namespace or to specific workloads via selector can override that setting to PERMISSIVE or DISABLE.

PeerAuthentication modes at a glance

Mode	Effect	When to use
`STRICT`	Only mTLS traffic is accepted	Enforce mutual TLS across services for strong security
`PERMISSIVE`	Accepts both plaintext and mTLS	Gradual rollout/migration to mTLS
`DISABLE`	Disables mTLS on targeted workloads	When specific services must allow plaintext only
`UNSET`	No explicit mode set	Falls back to higher-priority or default policy

Useful references

Istio: PeerAuthentication (mTLS)
istioctl analyze — use for policy validation and troubleshooting

For troubleshooting: know that a global PeerAuthentication in istio-system can be overridden by PeerAuthentication resources in a namespace or by selectors. Use istioctl analyze and kubectl get peerauthentications.security.istio.io -A to inspect effective policies.

The image shows a webpage from Istio's documentation about Peer Authentication, specifically focusing on MutualTLS settings.

Appendix — example YAMLs

Global strict (peer_auth_global.yaml):

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system
spec:
  mtls:
    mode: STRICT

Namespace override (peer_auth_default.yaml, permissive for all workloads in default):

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: default
spec:
  mtls:
    mode: PERMISSIVE

Namespace override with selector (permissive only for app=helloworld):

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: default
spec:
  selector:
    matchLabels:
      app: helloworld
  mtls:
    mode: PERMISSIVE

That completes this demo on PeerAuthentication and mTLS enforcement with Istio.

Introduction

Installation & Configuration

Traffic Management

Securing Workloads

Troubleshooting

Conclusion

Demo Authentication

1) Verify Istio automatic sidecar injection on namespaces

2) Deploy the helloworld sample

3) Create a test namespace and run a client pod

4) Verify connectivity from the test pod to helloworld

5) Enforce global mTLS with a PeerAuthentication

6) Enable injection for `test` namespace and retry

7) Override global policy at namespace scope (PERMISSIVE)

8) Target permissive mode to specific workloads (selector)

Test with an `app` namespace (non-injected)

PeerAuthentication modes at a glance

Useful references

Appendix — example YAMLs

Watch Video

Practice Lab

​1) Verify Istio automatic sidecar injection on namespaces

​2) Deploy the helloworld sample

​3) Create a test namespace and run a client pod

​4) Verify connectivity from the test pod to helloworld

​5) Enforce global mTLS with a PeerAuthentication

​6) Enable injection for test namespace and retry

​7) Override global policy at namespace scope (PERMISSIVE)

​8) Target permissive mode to specific workloads (selector)

​Test with an app namespace (non-injected)

​PeerAuthentication modes at a glance

​Useful references

​Appendix — example YAMLs

Watch Video

Practice Lab

1) Verify Istio automatic sidecar injection on namespaces

2) Deploy the helloworld sample

3) Create a test namespace and run a client pod

4) Verify connectivity from the test pod to helloworld

5) Enforce global mTLS with a PeerAuthentication

6) Enable injection for `test` namespace and retry

7) Override global policy at namespace scope (PERMISSIVE)

8) Target permissive mode to specific workloads (selector)

Test with an `app` namespace (non-injected)

PeerAuthentication modes at a glance

Useful references

Appendix — example YAMLs