Install ambient components

This step upgrades your Istio installation to include the ambient data plane components (ztunnel and updated CNI) while leaving all existing sidecar workloads without changes. Your sidecars will continue to handle traffic normally throughout this step.

Upgrade to the ambient profile

Using istioctl

Upgrade your existing Istio installation to use the ambient profile. This adds the ztunnel DaemonSet and updates the CNI plugin to support ambient mode:

$ istioctl upgrade --set profile=ambient

Using Helm

If you installed Istio with Helm, upgrade each component to add ambient support:

$ helm upgrade istio-base istio/base -n istio-system
$ helm upgrade istiod istio/istiod -n istio-system --set profile=ambient
$ helm upgrade istio-cni istio/cni -n istio-system --set profile=ambient
$ helm install ztunnel istio/ztunnel -n istio-system  # new component, not previously installed

Verify the ambient components

After the upgrade completes, verify that ztunnel and the updated CNI are running:

$ kubectl get pods -n istio-system

You should see the ztunnel DaemonSet pods running on every node, in addition to your existing Istiod and CNI pods:

NAME                                   READY   STATUS    RESTARTS   AGE
istio-cni-node-...                     1/1     Running   0          2m
istiod-...                             1/1     Running   0          2m
ztunnel-...                            1/1     Running   0          2m

Confirm ztunnel is running as a DaemonSet on all nodes:

$ kubectl get daemonset ztunnel -n istio-system

Enable HBONE support in existing sidecars

Sidecar proxies need to be restarted to pick up the new ISTIO_META_ENABLE_HBONE=true configuration that the ambient profile sets in MeshConfig. This enables sidecars to communicate with ambient-mode workloads using the HBONE protocol.

Restart each namespace that has sidecar injection enabled or restart your individual workloads based on your deployment strategy. For example, to restart a namespace:

$ kubectl rollout restart deployment -n <namespace>
$ kubectl rollout status deployment -n <namespace>

Repeat for each namespace containing sidecar-injected workloads.

To verify that HBONE support is active on a restarted pod:

$ kubectl get pod <pod-name> -n <namespace> -o json | \
    jq '.spec.initContainers[] | select(.name=="istio-proxy") | .env[] | select(.name=="ISTIO_META_ENABLE_HBONE")'

The output should show:

{
  "name": "ISTIO_META_ENABLE_HBONE",
  "value": "true"
}

Sidecar and ambient interoperability during migration

When a sidecar-injected pod communicates with a workload that has already been moved to ambient mode, the sidecar uses the HBONE protocol to tunnel traffic directly to the destination pod’s ztunnel.

The practical consequence is that L7 policies on the waypoint (such as HTTPRoute rules or AuthorizationPolicy with targetRefs) are not enforced for traffic coming from sidecar mode workloads during the migration period. The sidecar applies its own L7 logic before sending, but the waypoint never routes this traffic. This means L7 policies will not be applied twice because the sidecar handles its own routing decisions and the HBONE tunnel delivers traffic directly to the destination without processing again at the waypoint.

Deploy waypoint proxies (optional)

For namespaces that require L7 features, deploy a waypoint proxy now. The waypoint will be configured but not yet activated, traffic will continue to flow through sidecars.

Deploy a namespace scoped waypoint using istioctl:

$ istioctl waypoint apply -n <namespace>

Verify the waypoint pod is running:

$ kubectl get gateway waypoint -n <namespace>
$ kubectl get pods -n <namespace> -l gateway.istio.io/managed=istio.io-mesh-controller

For more details on waypoint configuration options (service-level, workload-level, or cross-namespace waypoints), see Using waypoint proxies.

Next steps

Proceed to Migrate policies to update your traffic and authorization policies for ambient mode.

If you have no VirtualService or DestinationRule resources, and your AuthorizationPolicy resources only use L4 rules (no HTTP method/path/header matching), skip that page and go directly to Enable ambient mode.