Skip to Content
✨ Check out our new MCP server! (tech preview)
Reference guidesIstio
Istio Logo

Get started

Istio  is an open source service mesh that layers transparently onto existing distributed applications. Istio’s powerful features provide a uniform and more efficient way to secure, connect and monitor services. Istio is the path to load balancing, service-to-service authentication and monitoring – with few or no service code changes.

Before getting into the chart’s possibilities, let’s start by deploying the default configuration:

helm install <release-name> oci://dp.apps.rancher.io/charts/istio -n istio-system --create-namespace \
    --set global.imagePullSecrets={application-collection}

Please check our authentication guide if you need to configure Application Collection OCI credentials in your Kubernetes cluster.

Wrapper chart overview

The Istio Helm chart offers a one-click installation solution, which installs the five official Istio charts as modified subcharts.

Istio subcharts

To achieve a one-command deployment without the use of external tools, we decided to use an original wrapper chart containing the following subcharts:

  • The base subchart, containing Istio CRDs, serviceAccounts and roles configurations. Default: enabled.
  • The cni subchart, which installs the CNI plug-in. Optionally used in sidecar mode. Default: disabled.
  • The gateway subchart, in case you prefer using the Istio gateway. Default: disabled.
  • The istiod subchart. Deploys the istiod service. Default: enabled.
  • The ztunnel subchart, only used in ambient mode. Default: disabled.

By default, our chart only installs the minimum components for Istio’s sidecar mode to work; the base and istiod subcharts.

As in any standard Helm chart, each subchart can be enabled by setting --set <subchartName>.enabled=true with any of their sub-parameters modified by using --set <subchartName>.<parameterKey>=<parameterValue>. The bundled README contains ordered lists of every configurable parameter.

Keep in mind that every subchart (even the base one) can be disabled or enabled as needed. This can be useful in some scenarios where you may want to only install a single subchart.

Chart configuration

To view the supported configuration options and documentation, run:

helm show values oci://dp.apps.rancher.io/charts/istio

Configuration profiles

The Istio Helm chart has the concept of a profile, which is a bundled collection of value presets. These can be set with --set <subchart>.profile=<profile>. For example, the demo profile offers a preset configuration to try out Istio in a test environment, with additional features enabled and lowered resource requirements.

For consistency, the same profiles are used across each subchart, even if they do not impact a given chart.

Explicitly set values have the highest priority, then profile settings, then chart defaults.

As an implementation detail of profiles, the default values for the chart are all nested under defaults. When configuring the chart, you should not include this. That is, --set <subchart>.some.field=true should be passed, not --set <subchart>.defaults.some.field=true.

helm install <release-name> oci://dp.apps.rancher.io/charts/istio -n istio-system --create-namespace \
    --set global.imagePullSecrets={application-collection} \
    --set base.profile=demo,istiod.profile=demo

By default, Istio uses the istio-system namespace.

Sidecar vs. Ambient mode

Istio supports two main data plane modes:

  • Sidecar mode, which deploys an Envoy proxy along with each pod that you start in your cluster.
  • Ambient mode, which uses a per-node Layer 4 proxy, and optionally a per-namespace Envoy proxy for Layer 7 features.

Sidecar mode

The Sidecar configuration provides a way to fine tune the set of ports and protocols that the proxy will accept when forwarding traffic to and from the workload.

helm install <release-name> oci://dp.apps.rancher.io/charts/istio -n istio-system --create-namespace \
    --set global.imagePullSecrets={application-collection}

Once installed, you’ll need to enable the sidecar auto-injection per namespace as follows:

kubectl label namespace default istio-injection=enabled

After labeling a namespace, every deployed pod will include an Istio proxy sidecar:

kubectl run nginx --image dp.apps.rancher.io/containers/nginx:1.31.3 \
    --overrides='{"spec": {"imagePullSecrets":[{"name": "application-collection"}]}}'
$ kubectl get pods
NAME    READY   STATUS    RESTARTS   AGE
nginx   2/2     Running   0          4s

Ambient mode

The ambient mode uses the base, cni, istiod and ztunnel subcharts. It will also require some modifications already included in the ambient profile.

helm install <release-name> oci://dp.apps.rancher.io/charts/istio -n istio-system --create-namespace \
    --set global.imagePullSecrets={application-collection} \
    --set cni.enabled=true,ztunnel.enabled=true \
    --set istiod.cni.enabled=true \
    --set cni.profile=ambient,istiod.profile=ambient,ztunnel.profile=ambient
$ kubectl get pods -n istio-system
NAME                      READY   STATUS    RESTARTS   AGE
istio-cni-node-vnvjg      1/1     Running   0          7m47s
istiod-855b86dcc7-7bftk   1/1     Running   0          7m47s
ztunnel-sh6ds             1/1     Running   0          7m47s

Operations

Use the Istio gateway

Install the gateway as a stand-alone

There are scenarios where you may want to only install the Istio Gateway. Provided the Istio control plane is already installed in the Kubernetes cluster, you can install just the Istio Gateway subchart by disabling the default ones:

helm install <release-name> oci://dp.apps.rancher.io/charts/istio -n istio-ingress --create-namespace \
    --set global.imagePullSecrets={application-collection} \
    --set base.enabled=false,istiod.enabled=false \
    --set gateway.enabled=true
$ kubectl get pods -n istio-ingress
NAME                             READY   STATUS    RESTARTS   AGE
istio-ingress-5b95765f5b-ghkkr   1/1     Running   0          3m56s

Install the gateway in a different namespace

By default, the Istio gateway will be installed in the chart’s namespace. This can be modified by overriding the gateway subchart’s namespace:

helm install <release-name> oci://dp.apps.rancher.io/charts/istio -n istio-system --create-namespace \
    --set global.imagePullSecrets={application-collection} \
    --set gateway.enabled=true,gateway.namespaceOverride=default

Upgrade the chart

There are two ways to upgrade your current Istio Helm chart:

  • Canary upgrade (sidecar and ambient mode)
  • In-place upgrade

Canary upgrade (sidecar mode)

Our Istio chart bundles the base and istiod subcharts in a single Helm chart release, unlike upstream Istio which ships them as separate charts. A canary install without base.enabled=false would attempt to claim CRDs already owned by the original release and fail with a Helm ownership conflict.

With an existing sidecar mode installation, install the canary control plane with a distinct revision name, omitting the base subchart:

helm install <release-name>-canary oci://dp.apps.rancher.io/charts/istio --version <new-version> \
    -n istio-system \
    --set global.imagePullSecrets={application-collection} \
    --set base.enabled=false \
    --set istiod.revision=canary

Migrate the existing workloads to the canary control plane as explained in the official documentation .

Once all workloads have been migrated and verified, run helm upgrade on the original release to update the CRDs and switch the default control plane to the new version:

helm upgrade <release-name> oci://dp.apps.rancher.io/charts/istio --version <new-version> \
    -n istio-system \
    --set global.imagePullSecrets={application-collection}

Once verified, uninstall the canary release:

helm uninstall <release-name>-canary -n istio-system

Canary upgrade (ambient mode)

In ambient mode, the canary covers the control plane (istiod) and waypoint proxies . ztunnel and istio-cni are cluster-wide DaemonSets with no revision concept and are always upgraded in-place as a separate step.

First, install the canary istiod revision alongside the existing installation. Note that cni.enabled=false skips deploying a second CNI DaemonSet (already running from the original release), while istiod.cni.enabled=true tells the canary control plane that CNI-based interception is in use:

helm install <release-name>-canary oci://dp.apps.rancher.io/charts/istio --version <new-version> \
    -n istio-system \
    --set global.imagePullSecrets={application-collection} \
    --set base.enabled=false \
    --set cni.enabled=false \
    --set ztunnel.enabled=false \
    --set istiod.revision=canary \
    --set istiod.cni.enabled=true \
    --set istiod.profile=ambient

After the canary installation, migrate your waypoint proxies to the canary revision by labeling the relevant Gateway resources:

kubectl label gateway <gateway-name> -n <namespace> istio.io/rev=canary

Once the waypoints are validated, commit the upgrade by running helm upgrade on the original release. This upgrades ztunnel, istio-cni, the base CRDs and the default control plane in-place:

helm upgrade <release-name> oci://dp.apps.rancher.io/charts/istio --version <new-version> \
    -n istio-system \
    --set global.imagePullSecrets={application-collection} \
    --set cni.enabled=true,ztunnel.enabled=true \
    --set istiod.cni.enabled=true \
    --set cni.profile=ambient,istiod.profile=ambient,ztunnel.profile=ambient

After the upgraded pods are running, remove the canary revision label from your waypoints so they reconnect to the upgraded default control plane:

kubectl label gateway <gateway-name> -n <namespace> istio.io/rev-

Once verified, uninstall the canary release:

helm uninstall <release-name>-canary -n istio-system

In-place upgrade

You can perform an in-place upgrade of Istio in your cluster using the built-in Helm upgrade workflow:

helm upgrade <release-name> oci://dp.apps.rancher.io/charts/istio -n istio-system \
    --set global.imagePullSecrets={application-collection}

This method is only viable when upgrading no more than one minor version at a time.

Uninstall the chart

Uninstalling the Istio Helm chart deletes the RBAC permissions and all resources hierarchically under the istio-system namespace. It is safe to ignore errors for non-existent resources because they may have been deleted hierarchically.

helm uninstall <release-name> -n istio-system

Our Istio chart uses hooks to achieve a one-click install. These hooks may need to be removed if you installed the chart in sidecar mode:

kubectl delete mutatingwebhookconfiguration istio-sidecar-injector
kubectl delete configmaps -n istio-system istio-sidecar-injector

The istio-system namespace is not removed by default. If no longer needed, use the following command to delete it:

kubectl delete namespace istio-system

The label to instruct Istio to automatically inject Envoy sidecar proxies is not removed by default. If no longer needed, use the following command to unlabel the namespaces that apply:

kubectl label namespace default istio-injection-

Due to Helm’s design , CustomResourceDefinitions (CRDs) are not removed when uninstalling the related chart. To do so, you will need to explicitly remove them:

kubectl delete $(kubectl get CustomResourceDefinition -l='app.kubernetes.io/part-of=istio' -o name -A)
Last updated on