Migration to Ambient Mode

1. Prepare the Cluster

To begin the migration, enable the ambient mesh profile during Istio installation or upgrade. This process deploys the ztunnel daemon to all nodes in your cluster. ztunnel serves as the core data plane component, managing transparent Layer 4 (L4) connectivity in the ambient model. If you haven't already done so, you'll also need to install istio-cni.

Upgrade istiod to use ambient mode:

helm upgrade istiod tetratelabs/istiod -n istio-system --set profile=ambient

Install or upgrade istio-cni to use ambient mode:

helm upgrade --install cni tetratelabs/cni -n istio-system --set profile=ambient

Deploy ztunnel to all nodes in your cluster:

helm install ztunnel tetratelabs/ztunnel -n istio-system

Additionally, ensure the Kubernetes Gateway API CRDs are installed and functioning correctly, as Ambient Mesh utilizes the Gateway API for Layer 7 (L7) routing and policy binding through Waypoint proxies.

For Gateway API installation, follow the instructions at: https://gateway-api.sigs.k8s.io/guides/#install-standard-channel

2. Transition Workloads to Ambient Mode

After deploying the ambient mesh components (including ztunnel), you can begin migrating your workloads. For workloads currently using sidecar injection, first remove the sidecar by updating their deployment configuration. This typically involves removing the sidecar.istio.io/inject: "true" annotation or disabling namespace-level sidecar injection if it was previously enabled globally.

To integrate workloads into the Ambient Data Plane, apply the following label to either the workload or its namespace:

istio.io/dataplane-mode=ambient

After applying this label, perform a rolling restart of the affected workloads. This step is crucial as it ensures pods are recreated without the sidecar proxy.

Traffic will now be captured by the ztunnel instance running on each node. To verify that a workload is properly enrolled in ambient mode, check for the following annotation:

k get <pod_name> -ojsonpath="{.metadata.annotations}"
{"ambient.istio.io/redirection":"enabled"}

or using istioctl:

istioctl ztunnel-config workload

Note: Workloads that never had sidecar injection enabled don't require a restart. They automatically become part of the ambient mesh once ztunnel is running.

At this stage, traffic between pods flows transparently through ztunnel at Layer 4 without requiring sidecar proxies. L4 policy enforcement is automatically applied.

3. Deploy Waypoint Proxies (If Needed)

For workloads requiring Layer 7 processing—such as HTTP routing, telemetry collection, or path-based AuthorizationPolicies—you'll need to deploy waypoint proxies. These are lightweight Envoy proxies that run as standalone pods, typically scoped to a specific namespace or service account.

Waypoint proxies manage L7 traffic routing and policy enforcement. Deploy a waypoint proxy using a Waypoint resource, associating it with a specific Service. This approach provides granular control over L7 logic application without the overhead of sidecar proxies on every pod.

For more information about Layer 7 processing and waypoints, refer to the official documentation.

4. Update Authorization Policies

Ambient Mesh introduces a new security policy binding model. Instead of using label selectors to attach AuthorizationPolicy or PeerAuthentication resources to workloads, you must now use the targetRef field.

Audit your existing policies and update them to use the targetRef field, pointing to the appropriate Service, Namespace, or ServiceAccount. This ensures proper policy enforcement in the ambient context, particularly when L7 processing is handled by waypoint proxies.

5. Activate and Verify Ambient Routing

After migrating workloads and deploying waypoints, verify that traffic flows as expected. Monitor metrics, conduct functional testing, and confirm that both L4 and L7 security policies are being enforced correctly.

If you encounter routing anomalies or policy enforcement issues, review your waypoint and policy configurations. Note that workloads in ambient mode maintain compatibility with sidecar-injected workloads, allowing for incremental migration without disrupting service connectivity.

6. Clean Up Sidecars and Legacy Configurations

Once you've confirmed that traffic and policies are functioning correctly with ambient mesh components, complete the migration by removing all remaining sidecar-related configurations from your manifests. This includes:

• Removing the sidecar.istio.io/inject annotation
• Disabling namespace-level injection if previously configured
• Cleaning up obsolete configurations such as:
  • DestinationRule subsets used for mTLS or sidecar-specific behaviors
  • AuthorizationPolicy resources using label selectors instead of targetRef
  • EnvoyFilter resources dependent on sidecar proxies

Note: The following Istio features are currently not supported in ambient mode:

• Multi-cluster mesh
• Virtual Machine (VM) integration
• SPIRE integration