Skip to main content

Documentation Index

Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt

Use this file to discover all available pages before exploring further.

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):
ConcernAmbient modeSidecar mode
Injection labelistio.io/dataplane-mode=ambientistio-injection=enabled
L4 interceptionztunnel (transparent)iptables + sidecar proxy
Workload containersNo sidecar per podSidecar container injected (2/2)
L7 featuresWaypoint proxy + Gateway APIVirtualService / Gateway / EnvoyFilter
References That completes the Ambient mode installation walkthrough and a basic demonstration of L4 interception with optional Waypoint L7 setup.

Watch Video

Practice Lab