Demo Ambient Mode Securing Workloads

This lesson demonstrates how Istio Ambient mode interacts with workload security (mTLS via PeerAuthentication and L3/L4 vs L7 AuthorizationPolicy enforcement). Ambient mode behavior is similar to traditional sidecar-mode flows but introduces important differences—most notably the waypoint proxy that enforces L7 policies. This guide is a hands-on demo for learning and experimentation. Prerequisites: a running Kubernetes cluster with Istio installed and Ambient mode enabled. Table of contents

Verify Istio control plane and ztunnel
Create a test curl pod
Deploy HelloWorld into the hello namespace
Enforce mTLS globally with PeerAuthentication
AuthorizationPolicy differences: L3/L4 vs L7 in Ambient mode
Configure the waypoint proxy for the hello namespace
AuthorizationPolicy for Ambient mode (targetRefs + principals)
Validate with a non-allowed namespace
Notes about service accounts and principals
Cleanup
Summary
Links and references

Verify Istio control-plane and ztunnel

Confirm Istio control-plane components are running (ztunnel, istiod, CNI):

kubectl get pods -n istio-system
# Example output:
# NAME                       READY   STATUS    RESTARTS   AGE
# istio-cni-node-zr8pb       1/1     Running   0          57s
# istiod-6b54648cc-ppq86     1/1     Running   0          65s
# ztunnel-9wjg7              1/1     Running   0          51s

Ensure ztunnel is present — it handles Ambient mode data-plane enforcement (L3/L4 mTLS).

Create a test pod for issuing requests

Create a lightweight curl pod in the test namespace to issue requests during the demo:

kubectl run curl --image=curlimages/curl -n test --restart=Never --command -- sleep infinity
kubectl get pods -n test
# pod/curl should be listed

This pod will act as a simple client for verifying connectivity and enforcement behavior.

Deploy the HelloWorld app into the `hello` namespace

From your demo directory (contains helloworld.yaml), label the hello namespace for Ambient dataplane mode and apply the manifest:

cd ~/demo
ls -l
kubectl label namespace hello istio.io/dataplane-mode=ambient
kubectl apply -f helloworld.yaml -n hello
# Example output:
# service/helloworld created
# deployment.apps/helloworld-v1 created
# deployment.apps/helloworld-v2 created

Verify deployments and service:

kubectl get pods -n hello
kubectl get svc -n hello
# Example output:
# NAME                               READY   STATUS    RESTARTS   AGE
# helloworld-v1-xxxxx                1/1     Running   0          9s
# helloworld-v2-xxxxx                1/1     Running   0          9s
#
# NAME         TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
# helloworld   ClusterIP   10.100.96.89   <none>        5000/TCP   13s

Enforce mTLS globally with PeerAuthentication

Create a global PeerAuthentication in the istio-system namespace to enforce mTLS STRICT across the mesh. Create global-pa.yaml:

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

Apply it and confirm:

kubectl apply -f global-pa.yaml
kubectl get peerauthentications.security.istio.io -A
# NAMESPACE      NAME      MODE    AGE
# istio-system   default   STRICT  6s

Now attempt to access HelloWorld from the test curl pod:

kubectl exec -n test curl -- curl --head http://helloworld.hello.svc.cluster.local:5000/hello

You will likely see a connection reset because mTLS is enforced and the test pod is not yet participating in Ambient dataplane mode. Example error:

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

Explanation: the hello namespace is labeled for Ambient mode but test is not. Ambient-mode enforcement expects the caller to be an ambient participant (or otherwise use mTLS-capable client identities). Label the test namespace for Ambient mode:

kubectl label namespace test istio.io/dataplane-mode=ambient

Retry the request:

kubectl exec -n test curl -- curl --head http://helloworld.hello.svc.cluster.local:5000/hello
# Example success:
# HTTP/1.1 200 OK
# Server: gunicorn
# Date: Mon, 01 Sep 2025 05:38:34 GMT
# Connection: keep-alive

In Ambient mode, mTLS enforcement is handled by the ztunnel at the dataplane layer. For successful communication, both caller and callee namespaces should be labeled with istio.io/dataplane-mode=ambient (or the client must present mTLS identity).

Authorization policies: layer-3/4 vs layer-7 differences

Ambient mode separates responsibilities:

L3/L4 (identity, mTLS) — enforced by ztunnel
L7 (HTTP route/method-level rules) — enforced by the waypoint proxy

This means AuthorizationPolicy behavior differs from sidecar mode. A policy that appears to be an L7 rule but lacks a configured waypoint or uses non-ambient constructs may be ignored or produce connection errors. Example: create a basic AuthorizationPolicy that attempts to allow only GET/HEAD from the test namespace. Save as hw-auth-policy.yaml:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: hello-world-auth-policy
  namespace: hello
spec:
  action: ALLOW
  selector:
    matchLabels:
      app: helloworld
  rules:
    - from:
        - source:
            namespaces: ["test"]
      to:
        - operation:
            methods: ["GET", "HEAD"]

Apply it:

kubectl apply -f hw-auth-policy.yaml
kubectl get authorizationpolicies.security.istio.io -A
# NAMESPACE  NAME                       ACTION  AGE
# hello      hello-world-auth-policy    ALLOW   5s

If you curl from test now, you may still get a connection reset or a 503. Why? Because the policy above is an L7 rule that relies on the waypoint to enforce route-level methods. Without a waypoint configured for the hello service, Ambient mode cannot reliably enforce this L7 policy and traffic may be rejected.

Configure the waypoint proxy for the `hello` namespace

Apply a waypoint for the hello namespace and label the namespace to use it:

istioctl waypoint apply -n hello
# Example output:
# ✔ waypoint hello/waypoint applied

Check pods to see the waypoint pod starting:

kubectl get pods -n hello
# NAME                           READY   STATUS    RESTARTS   AGE
# helloworld-v1-...              1/1     Running   0          5m
# helloworld-v2-...              1/1     Running   0          5m
# waypoint-...                   1/1     Running   0          10s

Label the namespace to use the waypoint:

kubectl label namespace hello istio.io/use-waypoint=waypoint
kubectl get ns hello --show-labels
# NAME   STATUS  AGE   LABELS
# hello  Active  9m    istio.io/dataplane-mode=ambient,istio.io/use-waypoint=waypoint, kubernetes.io/metadata.name=hello

Retry the curl from test:

kubectl exec -n test curl -- curl --head http://helloworld.hello.svc.cluster.local:5000/hello
# Example:
# HTTP/1.1 503 Service Unavailable
# server: istio-envoy
# x-envoy-decorator-operation: helloworld.hello.svc.cluster.local:5000/*

A 503 indicates the request is reaching the waypoint Envoy, but the L7 enforcement point is rejecting the request. This commonly happens because the AuthorizationPolicy is not expressed in a form Ambient mode expects for L7 enforcement.

When you enable a waypoint for L7 enforcement, ensure AuthorizationPolicy targets and identity principals are expressed explicitly. Using namespace selectors alone often does not work for L7 in Ambient mode.

AuthorizationPolicy for Ambient mode: use targetRefs + principals

Ambient mode follows a zero-trust, explicit model for L7 policies. Use targetRefs to point AuthorizationPolicy at a Service and principals to identify callers by mTLS identity (service account). Example hw-auth-policy-v2.yaml:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: hello-world-auth-policy
  namespace: hello
spec:
  targetRefs:
    - kind: Service
      group: ""
      name: helloworld
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - cluster.local/ns/test/sa/default
      to:
        - operation:
            methods: ["GET", "HEAD"]

Key differences from the earlier policy:

targetRefs targets the helloworld Service directly (L7 enforcement point expects explicit service targets).
from.source.principals uses the mTLS identity cluster.local/ns/<ns>/sa/<sa-name> instead of namespace selectors.

Apply the v2 policy and verify:

kubectl apply -f hw-auth-policy-v2.yaml
kubectl get authorizationpolicies.security.istio.io -A
# NAMESPACE  NAME                       ACTION  AGE
# hello      hello-world-auth-policy    ALLOW   4s

Retry from the test curl pod (default service account default in test namespace). It should now succeed:

kubectl exec -n test curl -- curl --head http://helloworld.hello.svc.cluster.local:5000/hello
# HTTP/1.1 200 OK

Validate the policy by testing from a non-allowed namespace

Create a new namespace web, label it for Ambient mode, and run an nginx pod. This pod will use the default service account in web, which is not allowed by the policy above.

kubectl create namespace web
kubectl label namespace web istio.io/dataplane-mode=ambient
kubectl run app -n web --image=nginx --restart=Never
kubectl get pods -n web

From the web pod, curl the HelloWorld service:

kubectl exec -n web app -- curl --head http://helloworld.hello.svc.cluster.local:5000/hello
# Expected result:
# HTTP/1.1 403 Forbidden
# content-length: 19
# content-type: text/plain
# server: istio-envoy
# x-envoy-decorator-operation: helloworld.hello.svc.cluster.local:5000/*

The 403 response indicates the incoming principal (e.g., cluster.local/ns/web/sa/default) is not allowed by the AuthorizationPolicy, which explicitly allowed only cluster.local/ns/test/sa/default.

Notes about service accounts and principals

Every namespace has a default service account. For least privilege and clearer policies, create dedicated service accounts for workloads and reference those in principals, for example: cluster.local/ns/<ns>/sa/<service-account>.
Prefer targetRefs (Service) + principals (service account identity) for L7 AuthorizationPolicy in Ambient mode. This pattern aligns with Ambient mode’s explicit, identity-based enforcement.
In sidecar mode, policies commonly use selector.matchLabels and namespaces. Ambient mode shifts L7 policy expression to service-targeted, identity-based constructs, enforced by the waypoint.

Quick comparison: Sidecar mode vs Ambient mode (L7 enforcement)

Aspect	Sidecar mode	Ambient mode
L7 enforcement location	Sidecar Envoy per workload	Waypoint proxy (per-service/namespace)
Common AuthorizationPolicy targeting	`selector.matchLabels` + `namespaces`	`targetRefs` (Service) + `principals` (mTLS identity)
mTLS enforcement	Sidecar dataplane	ztunnel (Ambient dataplane)
Typical failure modes	Misapplied label selectors	Missing waypoint or non-explicit principals

Cleanup (optional)

To remove demo resources:

kubectl delete -f hw-auth-policy-v2.yaml
kubectl delete -f hw-auth-policy.yaml || true
kubectl delete -f global-pa.yaml
kubectl delete -n web pod/app
kubectl delete pod/curl -n test
kubectl delete -n web namespace/web || true

Summary

Label namespaces with istio.io/dataplane-mode=ambient to participate in Ambient dataplane features.
Enforce mTLS via PeerAuthentication; ensure both caller and callee can perform mTLS.
For L7 AuthorizationPolicy in Ambient mode:
- Configure a waypoint for the target namespace/service.
- Prefer targetRefs + principals (service account-based mTLS identities) over namespace selectors.
Ambient mode separates L3/L4 enforcement (ztunnel) from L7 (waypoint) — this changes how policies need to be expressed. Expect behavior to evolve as Ambient mode matures.

Links and references

Istio Ambient Mode overview: https://istio.io/latest/docs/ops/deployment/ambient/
AuthorizationPolicy reference: https://istio.io/latest/docs/reference/config/security/authorization-policy/
PeerAuthentication reference: https://istio.io/latest/docs/reference/config/security/peer_authentication/
Kubernetes Basics: https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/

Introduction

Installation & Configuration

Traffic Management

Securing Workloads

Troubleshooting

Conclusion

Demo Ambient Mode Securing Workloads

Verify Istio control-plane and ztunnel

Create a test pod for issuing requests

Deploy the HelloWorld app into the `hello` namespace

Enforce mTLS globally with PeerAuthentication

Authorization policies: layer-3/4 vs layer-7 differences

Configure the waypoint proxy for the `hello` namespace

AuthorizationPolicy for Ambient mode: use targetRefs + principals

Validate the policy by testing from a non-allowed namespace

Notes about service accounts and principals

Quick comparison: Sidecar mode vs Ambient mode (L7 enforcement)

Cleanup (optional)

Summary

Links and references

Watch Video

Practice Lab

​Verify Istio control-plane and ztunnel

​Create a test pod for issuing requests

​Deploy the HelloWorld app into the hello namespace

​Enforce mTLS globally with PeerAuthentication

​Authorization policies: layer-3/4 vs layer-7 differences

​Configure the waypoint proxy for the hello namespace

​AuthorizationPolicy for Ambient mode: use targetRefs + principals

​Validate the policy by testing from a non-allowed namespace

​Notes about service accounts and principals

​Quick comparison: Sidecar mode vs Ambient mode (L7 enforcement)

​Cleanup (optional)

​Summary

​Links and references

Watch Video

Practice Lab

Verify Istio control-plane and ztunnel

Create a test pod for issuing requests

Deploy the HelloWorld app into the `hello` namespace

Enforce mTLS globally with PeerAuthentication

Authorization policies: layer-3/4 vs layer-7 differences

Configure the waypoint proxy for the `hello` namespace

AuthorizationPolicy for Ambient mode: use targetRefs + principals

Validate the policy by testing from a non-allowed namespace

Notes about service accounts and principals

Quick comparison: Sidecar mode vs Ambient mode (L7 enforcement)

Cleanup (optional)

Summary

Links and references