Install with Helm - Istio Io

{{< tip >}} Follow this guide to install and configure an Istio mesh with support for ambient mode. If you are new to Istio, and just want to try it out, follow the quick start instructions instead. {{< /tip >}}

We encourage the use of Helm to install Istio for production use in ambient mode. 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.)

Prerequisites

Check the Platform-Specific Prerequisites.
Install the Helm client, version 3.6 or above.
Configure the Helm repository:

{{< text syntax=bash snip_id=configure_helm >}} $ helm repo add istio https://istio-release.storage.googleapis.com/charts $ helm repo update {{< /text >}}

Install the control plane

Default configuration values can be changed using one or more --set <parameter>=<value> arguments. Alternatively, you can specify several parameters in a custom values file using the --values <file> argument.

{{< tip >}} You can display the default values of configuration parameters using the helm show values <chart> command or refer to Artifact Hub chart documentation for the base, istiod, CNI, ztunnel and Gateway chart configuration parameters. {{< /tip >}}

Full details on how to use and customize Helm installations are available in the sidecar installation documentation.

Unlike istioctl profiles, which group together components to be installed or removed, Helm profiles simply set groups of configuration values.

Base components

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.

{{< text syntax=bash snip_id=install_base >}} $ helm install istio-base istio/base -n istio-system --create-namespace --wait {{< /text >}}

Install or upgrade the Kubernetes Gateway API CRDs

istiod control plane

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.

{{< text syntax=bash snip_id=install_istiod >}} $ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait {{< /text >}}

CNI node agent

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).

{{< text syntax=bash snip_id=install_cni >}} $ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait {{< /text >}}

Install the data plane

ztunnel DaemonSet

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

{{< text syntax=bash snip_id=install_ztunnel >}} $ helm install ztunnel istio/ztunnel -n istio-system --wait {{< /text >}}

Ingress gateway (optional)

{{< tip >}} {{< boilerplate gateway-api-future >}} If you use the Gateway API, you do not need to install and manage an ingress gateway Helm chart as described below. Refer to the Gateway API task for details. {{< /tip >}}

To install an ingress gateway, run the command below:

{{< text syntax=bash snip_id=install_ingress >}} $ helm install istio-ingress istio/gateway -n istio-ingress --create-namespace --wait {{< /text >}}

If your Kubernetes cluster doesn't support the LoadBalancer service type (type: LoadBalancer) with a proper external IP assigned, run the above command without the --wait parameter to avoid the infinite wait. See Installing Gateways for in-depth documentation on gateway installation.

Configuration

To view supported configuration options and documentation, run:

{{< text syntax=bash >}} $ helm show values istio/istiod {{< /text >}}

Verify the installation

Verify the workload status

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

{{< text syntax=bash snip_id=show_components >}} $ helm ls -n istio-system NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION istio-base istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed base-{{< istio_full_version >}} {{< istio_full_version >}} istio-cni istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed cni-{{< istio_full_version >}} {{< istio_full_version >}} istiod istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed istiod-{{< istio_full_version >}} {{< istio_full_version >}} ztunnel istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed ztunnel-{{< istio_full_version >}} {{< istio_full_version >}} {{< /text >}}

You can check the status of the deployed pods with:

{{< text syntax=bash snip_id=check_pods >}} $ 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 {{< /text >}}

Verify with the sample application

After installing ambient mode with Helm, you can follow the Deploy the sample application guide to deploy the sample application and ingress gateways, and then you can add your application to the ambient mesh.

Uninstall

You can uninstall Istio and its components by uninstalling the charts installed above.

List all the Istio charts installed in istio-system namespace:

{{< text syntax=bash >}} $ helm ls -n istio-system NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION istio-base istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed base-{{< istio_full_version >}} {{< istio_full_version >}} istio-cni istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed cni-{{< istio_full_version >}} {{< istio_full_version >}} istiod istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed istiod-{{< istio_full_version >}} {{< istio_full_version >}} ztunnel istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed ztunnel-{{< istio_full_version >}} {{< istio_full_version >}} {{< /text >}}
(Optional) Delete any Istio gateway chart installations:

{{< text syntax=bash snip_id=delete_ingress >}} $ helm delete istio-ingress -n istio-ingress $ kubectl delete namespace istio-ingress {{< /text >}}
Delete the ztunnel chart:

{{< text syntax=bash snip_id=delete_ztunnel >}} $ helm delete ztunnel -n istio-system {{< /text >}}
Delete the Istio CNI chart:

{{< text syntax=bash snip_id=delete_cni >}} $ helm delete istio-cni -n istio-system {{< /text >}}
Delete the istiod control plane chart:

{{< text syntax=bash snip_id=delete_istiod >}} $ helm delete istiod -n istio-system {{< /text >}}
Delete the Istio base chart:

{{< tip >}} By design, deleting a chart via Helm doesn't delete the installed Custom Resource Definitions (CRDs) installed via the chart. {{< /tip >}}

{{< text syntax=bash snip_id=delete_base >}} $ helm delete istio-base -n istio-system {{< /text >}}
Delete CRDs installed by Istio (optional)

{{< warning >}} This will delete all created Istio resources. {{< /warning >}}

{{< text syntax=bash snip_id=delete_crds >}} $ kubectl get crd -oname | grep --color=never 'istio.io' | xargs kubectl delete {{< /text >}}
Delete the istio-system namespace:

{{< text syntax=bash snip_id=delete_system_namespace >}} $ kubectl delete namespace istio-system {{< /text >}}

Generate a manifest before installation

You can generate the manifests for each component before installing Istio using the helm template sub-command. For example, to generate a manifest that can be installed with kubectl for the istiod component:

{{< text syntax=bash snip_id=none >}} $ helm template istiod istio/istiod -n istio-system --kube-version {Kubernetes version of target cluster} > istiod.yaml {{< /text >}}

The generated manifest can be used to inspect what exactly is installed as well as to track changes to the manifest over time.

{{< tip >}} Any additional flags or custom values overrides you would normally use for installation should also be supplied to the helm template command. {{< /tip >}}

To install the manifest generated above, which will create the istiod component in the target cluster:

{{< text syntax=bash snip_id=none >}} $ kubectl apply -f istiod.yaml {{< /text >}}

{{< warning >}} If attempting to install and manage Istio using helm template, please note the following caveats:

The Istio namespace (istio-system by default) must be created manually.
Resources may not be installed with the same sequencing of dependencies as helm install
This method is not tested as part of Istio releases.
While helm install will automatically detect environment specific settings from your Kubernetes context, helm template cannot as it runs offline, which may lead to unexpected results. In particular, you must ensure that you follow these steps if your Kubernetes environment does not support third party service account tokens.
kubectl apply of the generated manifest may show transient errors due to resources not being available in the cluster in the correct order.
helm install automatically prunes any resources that should be removed when the configuration changes (e.g. if you remove a gateway). This does not happen when you use helm template with kubectl, and these resources must be removed manually.