---
title: "Deploy Istio Ambient Mode on your cluster"
description: "Deploy the bundled Istio Ambient Mode service mesh on clusters connected to Calico Cloud by applying the Istio custom resource, with prerequisites and limitations."
product: "Calico Cloud"
version: "v23.0.1"
section: "Compliance and security"
canonical_url: "https://docs.tigera.io/calico-cloud/compliance/istio/deploy-istio-ambient"
---

# Deploy Istio Ambient Mode on your cluster

You can deploy Calico's bundled version of Istio in ambient mode to provide mTLS encryption to your workloads.

> **SECONDARY:** Istio Ambient Mode is a tech preview feature. Tech preview features are subject to significant changes before they become GA.

## Limitations

- [Application layer network policies](https://docs.tigera.io/calico-cloud/network-policy/application-layer-policies/alp.md) are not compatible with the Istio service mesh.
- Istio Ambient Mode does not work together with [workload-based web application firewalls](https://docs.tigera.io/calico-cloud/threat/web-application-firewall.md).
- The service mesh is not supported for use on clusters that are also part of a [cluster mesh](https://docs.tigera.io/calico-cloud/multicluster.md).
- Destination ports are preserved only when Istio is deployed without Waypoint. If you deploy Waypoint, all traffic through Waypoint will show port 15008 as its destination port.
- Connect-time load balancing is not compatible with Istio Ambient Mode.

## Prerequisites

- Calico Cloud is installed and managed by the Tigera Operator.

## Install Istio in ambient mode on your cluster

You can create an Istio service mesh in ambient mode by creating the `Istio` custom resource.

- To install Istio in ambient mode, apply the `Istio` custom resource to your cluster:

  ```bash
  cat <<EOF | kubectl apply -f -
  apiVersion: operator.tigera.io/v1
  kind: Istio
  metadata:
    name: default
  EOF
  ```

  > **SECONDARY:** To customize resource requirements for your Istio deployment, see the options available in the [installation API documentation](https://docs.tigera.io/calico-cloud/reference/installation/api.md).

  To verify the installation:

  ```bash
  kubectl get tigerastatus
  ```

  Example output

  ```shell
  NAME                          AVAILABLE   PROGRESSING   DEGRADED   SINCE
  apiserver                     True        False         False      9m59s
  calico                        True        False         False      9m4s
  intrusion-detection           True        False         False      5m39s
  ippools                       True        False         False      10m
  istio                         True        False         False      19s
  log-collector                 True        False         False      8m34s
  log-storage                   True        False         False      10m
  log-storage-access            True        False         False      4m24s
  log-storage-dashboards        True        False         False      4m58s
  log-storage-elastic           True        False         False      5m4s
  log-storage-esmetrics         True        False         False      4m54s
  log-storage-kubecontrollers   True        False         False      5m9s
  log-storage-secrets           True        False         False      10m
  manager                       True        False         False      8m24s
  monitor                       True        False         False      9m44s
  policy-recommendation         True        False         False      9m24s
  tiers                         True        False         False      9m44s
  ```

  Now you can add your workloads to the Istio service mesh.

## Add a workload to the Istio service mesh

You can add workloads to the mesh by labeling them. Communication between labelled namespaces and pods goes through the mesh and uses mTLS encryption.

> **WARNING:** Don't label Calico Cloud resources to add them to the service mesh. Doing this can cause interruptions and failure to your cluster network.
>
> If you want to secure Calico Cloud components, see [Secure Calico component communications](https://docs.tigera.io/calico-cloud/operations/comms.md).

1. To add workloads to your Istio service mesh, add the `istio.io/dataplane-mode=ambient` label to a pod or namespace resource:

   Adding a namespace to the Istio service mesh

   ```bash
   kubectl label namespace <namespace> istio.io/dataplane-mode=ambient
   ```

   Replace `<namespace>` with the namespace you want to include in the mesh.

   Adding a pod to the Istio service mesh

   ```bash
   kubectl label pod --namespace=<namespace> <pod> istio.io/dataplane-mode=ambient
   ```

   Replace the following:

   - `<pod>`: The name of the pod you want to include in the mesh.
   - `<namespace>`: The namespace your pod is in.

## Removing Istio

If you want to remove Istio, first remove the labels you applied to pods and namespaces. When that's done, you can delete the `Istio` custom resource.

1. Remove the label from namespaces and pods by running the following commands:

   ```bash
   kubectl label namespaces --all istio.io/dataplane-mode=ambient-
   kubectl label pods --all --all-namespaces istio.io/dataplane-mode=ambient-
   ```

2. Remove the `Istio` custom resource:

   ```bash
   kubectl delete istio.operator.tigera.io default
   ```

## Troubleshooting commands

Check whether Istio pods are deployed:

```bash
kubectl get pods -n calico-system | grep 'istio\|ztunnel'
```

Check whether Istio CRDs are deployed:

```bash
kubectl get crd | grep istio
```

Check which pods and namespaces are in the mesh:

- Requires [istioctl](https://istio.io/latest/docs/ops/diagnostic-tools/istioctl/).

```bash
istioctl ztunnel-config workloads -n calico-system
```

Check for errors logged by the zTunnel component:

```bash
ZTUNNEL_PODS=$(kubectl get pod -n calico-system \
  -l app.kubernetes.io/name=ztunnel \
  -o jsonpath='{.items[*].metadata.name}')

for P in $ZTUNNEL_PODS; do
  echo "--- Checking logs for pod: $P ---"
  kubectl logs $P -n calico-system 2>/dev/null | \
    grep -i error | \
    grep -i app1
done
```

## Additional resources

- [Overview of Istio ambient mode](https://istio.io/latest/docs/ambient/overview/).
- [Configuration options](https://docs.tigera.io/calico-cloud/reference/installation/api.md).