Skip to content

Commit 331be7c

Browse files
ctauchenclaude
ctauchen
and
claude
committed
Add Istio Ambient Mode docs to Calico Cloud 22.2
Port the Istio Ambient Mode pages from Calico Enterprise 3.22 into the Calico Cloud 22.2 versioned docs, wire them into the Compliance and security sidebar category, and add a corresponding feature entry to the March 5, 2026 (22.2.0) release notes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 1e7e7b6 commit 331be7c

4 files changed

Lines changed: 232 additions & 0 deletions

File tree

‎calico-cloud_versioned_docs/version-22-2/compliance/istio/about-istio-ambient.mdx‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
description: An overview of Calico's bundled version of Istio Ambient Mode
3+
---
4+
5+
# Istio Ambient Mode
6+
7+
You can use $[prodname] to deploy and manage an Istio service mesh on your cluster.
8+
$[prodname] installs Istio in ambient mode, which conserves resources while providing the same robust mTLS encryption for your workloads.
9+
10+
:::note
11+
12+
Istio Ambient Mode is a tech preview feature.
13+
Tech preview features are subject to significant changes before they become GA.
14+
15+
:::
16+
17+
## About Istio Ambient Mode
18+
19+
Istio is a service mesh that manages and secures communication between microservices.
20+
Typically, Istio uses sidecar proxies that are deployed alongside every pod in the service mesh.
21+
At scale, running these sidecar proxies can be difficult to manage and a drain on resources.
22+
23+
Istio Ambient Mode is a simplified service mesh architecture that removes the need for a sidecar proxy next to every pod.
24+
Instead, it uses node-level components for shared security and a layered approach for advanced traffic management.
25+
This design saves on computing resources and simplifies operations.
26+
27+
## About Istio Ambient Mode on Calico
28+
29+
$[prodname] provides a bundled version of Istio that can be installed and managed by the Tigera Operator.
30+
31+
This integration automates the lifecycle of the Istio components to reduce manual configuration overhead.
32+
CVEs are addressed as part of the regular $[prodname] patch release cadence.
33+
Administrators provision the Istio service mesh by defining a standard `Istio` custom resource.
34+
35+
### The enhanced zTunnel proxy
36+
37+
The zTunnel component in Istio Ambient Mode is a lightweight proxy that runs on every node.
38+
39+
Its main job is to handle encryption, authentication, and policy enforcement for traffic at Layer 4.
40+
41+
A challenge in the original Istio Ambient Mode is that when traffic is routed through the zTunnel, it gets placed into a tunnel on a specific port (15008).
42+
This change makes it impossible for existing Layer 3 or Layer 4 network policies (like those from Calico) to see the original destination port of the traffic.
43+
44+
Calico addresses this by using an enhanced zTunnel that is modified to preserve the original destination port.
45+
This modification allows existing Calico and Kubernetes network policies to continue functioning exactly as they did before, without needing any rewrites, even though the traffic is now encrypted with mTLS.
46+
47+
These zTunnel enhancements are not compatible with Istio's application-layer Waypoint proxy.
48+
If you deploy Waypoint, the reported destination ports will follow the original behavior.
49+
Existing network policies need to be adapted to allow communication to port 15008.
50+
51+
## Additional resources
52+
* [Overview of Istio ambient mode](https://istio.io/latest/docs/ambient/overview/).
53+
* [Ambient and Kubernetes NetworkPolicy](https://istio.io/latest/docs/ambient/usage/networkpolicy/)

‎calico-cloud_versioned_docs/version-22-2/compliance/istio/deploy-istio-ambient.mdx‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
description: This page explains how to deploy Calico's bundled version of Istio in ambient mode.
3+
---
4+
5+
# Deploy Istio Ambient Mode on your cluster
6+
7+
You can deploy Calico's bundled version of Istio in ambient mode to provide mTLS encryption to your workloads.
8+
9+
:::note
10+
11+
Istio Ambient Mode is a tech preview feature.
12+
Tech preview features are subject to significant changes before they become GA.
13+
14+
:::
15+
16+
## Limitations
17+
18+
* [Application layer network policies](../../network-policy/application-layer-policies/alp.mdx) are not compatible with the Istio service mesh.
19+
* Istio Ambient Mode does not work together with [workload-based web application firewalls](../../threat/web-application-firewall.mdx).
20+
* The service mesh is not supported for use on clusters that are also part of a [cluster mesh](../../multicluster/index.mdx).
21+
* Destination ports are preserved only when Istio is deployed without Waypoint.
22+
If you deploy Waypoint, all traffic through Waypoint will show port 15008 as its destination port.
23+
* Connect-time load balancing is not compatible with Istio Ambient Mode.
24+
25+
## Prerequisites
26+
27+
* $[prodname] is installed and managed by the Tigera Operator.
28+
29+
## Install Istio in ambient mode on your cluster
30+
31+
You can create an Istio service mesh in ambient mode by creating the `Istio` custom resource.
32+
33+
* To install Istio in ambient mode, apply the `Istio` custom resource to your cluster:
34+
35+
```bash
36+
cat <<EOF | kubectl apply -f -
37+
apiVersion: operator.tigera.io/v1
38+
kind: Istio
39+
metadata:
40+
name: default
41+
EOF
42+
```
43+
44+
:::note
45+
To customize resource requirements for your Istio deployment, see the options available in the [installation API documentation](../../reference/installation/api.mdx).
46+
:::
47+
48+
To verify the installation:
49+
50+
```bash
51+
kubectl get tigerastatus
52+
```
53+
54+
```shell title='Example output'
55+
NAME AVAILABLE PROGRESSING DEGRADED SINCE
56+
apiserver True False False 9m59s
57+
calico True False False 9m4s
58+
intrusion-detection True False False 5m39s
59+
ippools True False False 10m
60+
// highlight-next-line
61+
istio True False False 19s
62+
log-collector True False False 8m34s
63+
log-storage True False False 10m
64+
log-storage-access True False False 4m24s
65+
log-storage-dashboards True False False 4m58s
66+
log-storage-elastic True False False 5m4s
67+
log-storage-esmetrics True False False 4m54s
68+
log-storage-kubecontrollers True False False 5m9s
69+
log-storage-secrets True False False 10m
70+
manager True False False 8m24s
71+
monitor True False False 9m44s
72+
policy-recommendation True False False 9m24s
73+
tiers True False False 9m44s
74+
```
75+
Now you can add your workloads to the Istio service mesh.
76+
77+
## Add a workload to the Istio service mesh
78+
79+
You can add workloads to the mesh by labeling them.
80+
Communication between labelled namespaces and pods goes through the mesh and uses mTLS encryption.
81+
82+
:::warning
83+
84+
Don't label $[prodname] resources to add them to the service mesh.
85+
Doing this can cause interruptions and failure to your cluster network.
86+
87+
If you want to secure $[prodname] components, see [Secure Calico component communications](../../operations/comms/index.mdx).
88+
:::
89+
90+
1. To add workloads to your Istio service mesh, add the `istio.io/dataplane-mode=ambient` label to a pod or namespace resource:
91+
92+
```bash title='Adding a namespace to the Istio service mesh'
93+
kubectl label namespace <namespace> istio.io/dataplane-mode=ambient
94+
```
95+
Replace `<namespace>` with the namespace you want to include in the mesh.
96+
97+
```bash title='Adding a pod to the Istio service mesh'
98+
kubectl label pod --namespace=<namespace> <pod> istio.io/dataplane-mode=ambient
99+
```
100+
Replace the following:
101+
* `<pod>`: The name of the pod you want to include in the mesh.
102+
* `<namespace>`: The namespace your pod is in.
103+
104+
## Removing Istio
105+
106+
If you want to remove Istio, first remove the labels you applied to pods and namespaces.
107+
When that's done, you can delete the `Istio` custom resource.
108+
109+
1. Remove the label from namespaces and pods by running the following commands:
110+
111+
```bash
112+
kubectl label namespaces --all istio.io/dataplane-mode=ambient-
113+
kubectl label pods --all --all-namespaces istio.io/dataplane-mode=ambient-
114+
```
115+
1. Remove the `Istio` custom resource:
116+
117+
```bash
118+
kubectl delete istio.operator.tigera.io default
119+
```
120+
121+
## Troubleshooting commands
122+
123+
Check whether Istio pods are deployed:
124+
125+
```bash
126+
kubectl get pods -n calico-system | grep 'istio\|ztunnel'
127+
```
128+
129+
Check whether Istio CRDs are deployed:
130+
131+
```bash
132+
kubectl get crd | grep istio
133+
```
134+
135+
Check which pods and namespaces are in the mesh:
136+
137+
* Requires [istioctl](https://istio.io/latest/docs/ops/diagnostic-tools/istioctl/).
138+
139+
```bash
140+
istioctl ztunnel-config workloads -n calico-system
141+
```
142+
143+
Check for errors logged by the zTunnel component:
144+
145+
```bash
146+
ZTUNNEL_PODS=$(kubectl get pod -n calico-system \
147+
-l app.kubernetes.io/name=ztunnel \
148+
-o jsonpath='{.items[*].metadata.name}')
149+
150+
for P in $ZTUNNEL_PODS; do
151+
echo "--- Checking logs for pod: $P ---"
152+
kubectl logs $P -n calico-system 2>/dev/null | \
153+
grep -i error | \
154+
grep -i app1
155+
done
156+
```
157+
158+
## Additional resources
159+
160+
* [Overview of Istio ambient mode](https://istio.io/latest/docs/ambient/overview/).
161+
* [Configuration options](../../reference/installation/api).

‎calico-cloud_versioned_docs/version-22-2/release-notes/index.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,15 @@ To configure notifications, click the user icon <IconUser width="20"/> **> Notif
3030

3131
### New features and enhancements
3232

33+
#### Istio Ambient Mode (tech preview)
34+
35+
$[prodname] now provides a bundled version of Istio in ambient mode, a sidecarless architecture that delivers robust mTLS encryption and service mesh security while significantly reducing resource consumption and operational overhead.
36+
This implementation, managed by the Tigera Operator, features an enhanced zTunnel proxy that preserves original destination ports so existing Calico and Kubernetes network policies continue to function seamlessly without requiring rewrites.
37+
38+
For more information, see [Istio Ambient Mode](../compliance/istio/about-istio-ambient.mdx).
39+
40+
#### Enhancements
41+
3342
* Enhancements to to Calico Cloud dashboards.
3443

3544
<h2 id="february-5-2026">February 5, 2026 (web console update)</h2>

‎calico-cloud_versioned_sidebars/version-22-2-sidebars.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -400,6 +400,15 @@
400400
"id": "compliance/index"
401401
},
402402
"items": [
403+
{
404+
"type": "category",
405+
"label": "Istio Ambient Mode",
406+
"link": null,
407+
"items": [
408+
"compliance/istio/about-istio-ambient",
409+
"compliance/istio/deploy-istio-ambient"
410+
]
411+
},
403412
"compliance/enable-compliance",
404413
"compliance/overview",
405414
"compliance/compliance-reports-cis",

0 commit comments

Comments
 (0)