Demo Install Istio Ambient Mode via CLI

This guide shows how to install Istio in Ambient mode using the istioctl CLI. Ambient mode differs from the classic sidecar approach primarily in the profile you install and how you label namespaces. The steps below walk through download, install, namespace labeling, smoke tests, enabling Layer 7 with waypoint proxies, and optional cleanup. Commands and sample outputs are included for quick verification.

Prerequisites

A Kubernetes cluster (kubectl configured).
Permissions to create CRDs, namespaces, and cluster-level resources.
A supported Istio release (examples use 1.26.3).

1) Download Istio and add istioctl to PATH

Download a specific Istio release and add istioctl to your PATH:

curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.26.3 sh -
cd istio-1.26.3
export PATH=$PWD/bin:$PATH

Sample installer output (trimmed):

# ... download progress ...
Istio 1.26.3 download complete!

To configure the istioctl client tool for your workstation,
add the /root/istio-1.26.3/bin directory to your environment path variable with:
    export PATH="$PATH:/root/istio-1.26.3/bin"

Begin the Istio pre-installation check by running:
    istioctl x precheck

Verify the client version (the cluster will not have Istio pods yet):

istioctl version

Example output:

Istio is not present in the cluster: no running Istio pods in namespace "istio-system"
client version: 1.26.3

2) Install Istio with the ambient profile

Install Istio using the Ambient profile. This configures control-plane components and the Ambient dataplane components (ztunnel + istio-cni):

istioctl install --set profile=ambient -y

The installer prints progress and the resources it creates. After the installation finishes, confirm the core control-plane and dataplane components are running:

kubectl get pods -n istio-system

Example output:

NAME                       READY   STATUS    RESTARTS   AGE
istio-cni-node-rc84w       1/1     Running   0          3m
istiod-6b854648cc-z54lj    1/1     Running   0          3m
ztunnel-kbc9c              1/1     Running   0          3m

Notes:

Ambient mode uses ztunnel to perform transparent L4 interception, while istio-cni (DaemonSet) handles per-node networking/CNI tasks.
On a multi-node cluster, daemonsets (istio-cni and ztunnel) will typically show one pod per node.

You can explicitly list daemonsets:

kubectl get ds -n istio-system

3) Label the namespace for Ambient dataplane mode

Ambient mode does not rely on istio-injection=enabled. Instead, label the namespace with istio.io/dataplane-mode=ambient. Check current namespaces and labels:

kubectl get ns --show-labels

Example output before labeling:

NAME               STATUS   AGE    LABELS
default            Active   3m7s   kubernetes.io/metadata.name=default
istio-system       Active   73s    kubernetes.io/metadata.name=istio-system
kube-system        Active   3m7s   kubernetes.io/metadata.name=kube-system

Istio analyzer may report suggestions oriented to sidecar injection. For example:

istioctl analyze -n default

Sample analyzer info:

Info [IST0102] (Namespace default) The namespace is not enabled for Istio injection. Run 'kubectl label namespace default istio-injection=enabled' to enable it, or 'kubectl label namespace default istio-injection=disabled' to explicitly mark it as not needing injection.

For Ambient mode, set the dataplane label:

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

Verify the label:

kubectl get ns --show-labels

Example output after labeling:

NAME        STATUS   AGE     LABELS
default     Active   4m28s   istio.io/dataplane-mode=ambient,kubernetes.io/metadata.name=default
istio-system Active  2m34s   kubernetes.io/metadata.name=istio-system

Ambient mode uses istio.io/dataplane-mode=ambient instead of istio-injection=enabled. istioctl analyze may still show messages for sidecar-style injection even after you label a namespace for ambient mode.

4) Run a test pod and verify L4 interception

Create a simple test pod (NGINX) in the labeled namespace and check its state:

kubectl run test --image=nginx
kubectl get pods

Expected pod state:

NAME   READY   STATUS    RESTARTS   AGE
test   1/1     Running   0          30s

Notice: Unlike sidecar mode, the pod will not show a second container (no 2/2). Ambient mode relies on ztunnel for transparent L4 interception rather than injecting a sidecar into every workload. Confirm Istio system pods:

kubectl get pods -n istio-system

Tail the ztunnel logs to observe intercepted L4 traffic. First list the ztunnel pod:

kubectl get pods -n istio-system

Then stream logs (replace the pod name with your actual pod name):

kubectl logs -n istio-system -f ztunnel-kbc9c

You should see lines indicating listeners and xDS updates:

2025-08-30T19:40:45.581334Z info proxy::outbound listener established address=[::]:15001 component="outbound" transparent=true
2025-08-30T19:40:50.354853Z info xds::client:xds{id=1} received response type_url="type.googleapis.com/istio.workload.Address" size=1 removes=0

From another terminal, make an outbound request from the test pod:

kubectl exec test -- curl --head www.google.com

Sample HTTP response:

HTTP/1.1 200 OK
Content-Type: text/html; charset=ISO-8859-1
Date: Sat, 30 Aug 2025 19:41:57 GMT
Server: gws
...

And the ztunnel access log should show the intercepted outbound connection:

2025-08-30T19:41:57.039950Z info access connection complete src.addr=10.50.0.7:46996 src.workload="test" src.namespace="default" dst.addr=74.125.126.104:80 direction="outbound" bytes_sent=79 bytes_recv=1028 duration="63ms"

This confirms ztunnel is intercepting and routing L4 traffic for workloads in the namespace labeled with istio.io/dataplane-mode=ambient.

5) CRDs and waypoint proxy for Layer 7 (L7) functionality

Ambient mode provides transparent L4 interception out of the box. To enable Layer 7 capabilities like routing, fault injection, and traffic mirroring, Istio introduces the waypoint proxy and integrates with the Kubernetes Gateway API (e.g., HTTPRoute). These L7 features require additional CRDs beyond the core Istio CRDs. List CRDs installed by Istio:

kubectl get crd

Common Istio CRDs include:

CRD (examples)
`authorizationpolicies.security.istio.io`
`destinationrules.networking.istio.io`
`envoyfilters.networking.istio.io`
`gateways.networking.istio.io`
`virtualservices.networking.istio.io`
`wasmplugins.extensions.istio.io`
`workloadentries.networking.istio.io`
`workloadgroups.networking.istio.io`

After enabling waypoint and Gateway API resources you may also see:

Gateway API CRDs
`gatewayclasses.gateway.networking.k8s.io`
`httproutes.gateway.networking.k8s.io`
`referencegrants.gateway.networking.k8s.io`
`grpcroutes.gateway.networking.k8s.io`

To enable a waypoint proxy for a namespace (example uses default):

istioctl waypoint apply -n default

Sample output:

✅ waypoint default/waypoint applied

After applying, check for the waypoint Deployment and pods:

kubectl get pods -n default

Example:

NAME                             READY   STATUS    RESTARTS   AGE
test                             1/1     Running   0          2m
waypoint-7cb5d4bd6-crnmp         1/1     Running   0          7s

The waypoint proxy is responsible for Layer 7 capabilities in Ambient mode and integrates with Kubernetes Gateway API resources (HTTPRoute, GatewayClass, etc.). These APIs are separate from classic Istio VirtualService resources and require the corresponding CRDs.

Waypoint proxies enable Layer 7 features in Ambient mode using the Kubernetes Gateway API (HTTPRoute, GatewayClass, etc.). These APIs and CRDs are separate from classic Istio VirtualService resources.

6) Delete the waypoint proxy (optional)

To remove the waypoint proxy in the namespace:

istioctl waypoint delete --all -n default

Sample output:

waypoint default/waypoint deleted

The waypoint Pod/Deployment may take a short time to terminate.

7) What matters for the ICA exam and practical checks

Key points to remember and verify:

Install Istio Ambient mode:
- istioctl install --set profile=ambient -y
- Label namespaces with istio.io/dataplane-mode=ambient
Confirm L4 interception by inspecting ztunnel logs and verifying outbound connections from application pods.
Waypoint proxy + Kubernetes Gateway API provide L7 capabilities in Ambient mode; they require additional CRDs (HTTPRoute, GatewayClass, etc.).
Deep configuration of HTTPRoute, VirtualService, or EnvoyFilter for Ambient L7 is generally outside the core ICA exam scope.

Comparison (Ambient vs Sidecar):

Concern	Ambient mode	Sidecar mode
Injection label	`istio.io/dataplane-mode=ambient`	`istio-injection=enabled`
L4 interception	ztunnel (transparent)	iptables + sidecar proxy
Workload containers	No sidecar per pod	Sidecar container injected (2/2)
L7 features	Waypoint proxy + Gateway API	VirtualService / Gateway / EnvoyFilter

References

Istio Waypoint docs: https://istio.io/latest/docs/tasks/traffic-management/waypoint/
Kubernetes Gateway API: https://gateway-api.sigs.k8s.io/
Istio VirtualService: https://istio.io/latest/docs/reference/config/networking/virtual-service/
Istio EnvoyFilter: https://istio.io/latest/docs/reference/config/networking/envoy-filter/

That completes the Ambient mode installation walkthrough and a basic demonstration of L4 interception with optional Waypoint L7 setup.

Demo Install Istio Ambient Mode via CLI

Prerequisites

1) Download Istio and add istioctl to PATH

2) Install Istio with the ambient profile

3) Label the namespace for Ambient dataplane mode

4) Run a test pod and verify L4 interception

5) CRDs and waypoint proxy for Layer 7 (L7) functionality

6) Delete the waypoint proxy (optional)

7) What matters for the ICA exam and practical checks

Watch Video

Practice Lab

​Prerequisites

​1) Download Istio and add istioctl to PATH

​2) Install Istio with the ambient profile

​3) Label the namespace for Ambient dataplane mode

​4) Run a test pod and verify L4 interception

​5) CRDs and waypoint proxy for Layer 7 (L7) functionality

​6) Delete the waypoint proxy (optional)

​7) What matters for the ICA exam and practical checks

Watch Video

Practice Lab

Prerequisites

1) Download Istio and add istioctl to PATH

2) Install Istio with the ambient profile

3) Label the namespace for Ambient dataplane mode

4) Run a test pod and verify L4 interception

5) CRDs and waypoint proxy for Layer 7 (L7) functionality

6) Delete the waypoint proxy (optional)

7) What matters for the ICA exam and practical checks