Documentation
Setup
Installation

Installation

The best method for a production-ready ambient mesh installation is Helm. Other methods, like istioctl install or the script used by the quickstart guide, use Istio’s Helm charts under the hood.

Check pre-requisites for your platform

Custom configuration is provided for some Kubernetes enviroments. Make sure you have read the system requirements before proceeding.

Install the control plane

To allow controlled upgrades, the control plane and data plane components are packaged and installed separately. Because the ambient data plane is split across two components, the ztunnel and waypoints, upgrades involve separate steps for these components.

Install the Kubernetes Gateway API

Ambient mesh is configured using the Gateway API, the next-generation API for routing built by the Kubernetes project. The APIs are not installed by default on most clusters, so install the latest version:

Install the Kubernetes Gateway API
$ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
  { kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml; }

Add the Helm chart repository

Install and update the Istio repo from its chart repository.

helm repo add istio https://istio-release.storage.googleapis.com/charts
helm repo update istio

Install the control plane

The base chart contains the basic CRDs and cluster roles required to set up Istio. This should be installed prior to any other Istio component.

$ helm install istio-base istio/base -n istio-system --create-namespace --wait

The istiod chart installs a revision of Istiod. Istiod is the control plane component that manages and configures the proxies to route traffic within the mesh.

$ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait

The cni chart installs the Istio CNI node agent. It is responsible for detecting the pods that belong to the ambient mesh, and configuring the traffic redirection between pods and the ztunnel node proxy (which will be installed later).

$ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait

Install the data plane

The ztunnel chart installs the ztunnel DaemonSet, which is the node proxy component of Istio’s ambient mode.

$ helm install ztunnel istio/ztunnel -n istio-system --wait

Verify the installation

After installing all the components, you can check the Helm deployment status with:

$ helm ls -n istio-system
NAME            NAMESPACE       REVISION    UPDATED                                 STATUS      CHART           APP VERSION
istio-base      istio-system    1           2024-10-27 22:14:45.964722028 +0000 UTC deployed    base-1.24.0     1.24.0
istio-cni       istio-system    1           2024-10-27 22:14:45.964722028 +0000 UTC deployed    cni-1.24.0      1.24.0
istiod          istio-system    1           2024-10-27 22:14:45.964722028 +0000 UTC deployed    istiod-1.24.0   1.24.0
ztunnel         istio-system    1           2024-10-27 22:14:45.964722028 +0000 UTC deployed    ztunnel-1.24.0  1.24.0

You can check the status of the deployed pods with:

$ kubectl get pods -n istio-system
NAME                             READY   STATUS    RESTARTS   AGE
istio-cni-node-g97z5             1/1     Running   0          10m
istiod-5f4c75464f-gskxf          1/1     Running   0          10m
ztunnel-c2z4s                    1/1     Running   0          10m
System and app requirementsAdd workloads to the mesh