Install with Helm

Install with Helm

Follow this guide to install and configure an Istio mesh using Helm for in-depth evaluation. The Helm charts used in this guide are the same underlying charts used when installing Istio via Istioctl or the Operator.

This feature is currently considered alpha.

Prerequisites

Download the Istio release.
Perform any necessary platform-specific setup.
Check the Requirements for Pods and Services.
Install a Helm client with a version higher than 3.1.1.

Helm 2 is not supported for installing Istio.

The commands in this guide use the Helm charts that are included in the Istio release package.

Installation steps

Change directory to the root of the release package and then follow the instructions below.

Create a namespace istio-system for Istio components:

$ kubectl create namespace istio-system
Install the Istio base chart which contains cluster-wide resources used by the Istio control plane:

$ helm install --namespace istio-system istio-base manifests/charts/base

The default chart configuration uses the secure third party tokens for service account token projections used by Istio proxies to authenticate with the Istio control plane. Before proceeding to install any of the charts below, you should verify if third party tokens are enabled in your cluster by following the steps describe here. If third party tokens are not enabled, you should add the option --set global.jwtPolicy=first-party-jwt to the Helm install commands. If the jwtPolicy is not set correctly, pods associated with istiod, gateways or workloads with injected Envoy proxies will not get deployed due to the missing istio-token volume.
Install the Istio discovery chart which deploys the istiod service:

$ helm install --namespace istio-system istiod manifests/charts/istio-control/istio-discovery \ --set global.hub="docker.io/istio" --set global.tag="1.8.0"
(Optional) Install the Istio ingress gateway chart which contains the ingress gateway components:

$ helm install --namespace istio-system istio-ingress manifests/charts/gateways/istio-ingress \ --set global.hub="docker.io/istio" --set global.tag="1.8.0"
(Optional) Install the Istio egress gateway chart which contains the egress gateway components:

$ helm install --namespace istio-system istio-egress manifests/charts/gateways/istio-egress \ --set global.hub="docker.io/istio" --set global.tag="1.8.0"

Verifying the installation

Ensure all Kubernetes pods in istio-system namespace are deployed and have a STATUS of Running:

$ kubectl get pods -n istio-system

Updating your Istio configuration

You can provide override settings specific to any Istio Helm chart used above and follow the Helm upgrade workflow to customize your Istio mesh installation. The available configurable options can be found by inspecting the top level values.yaml file associated with the Helm charts located at manifests/charts inside the Istio release package specific to your version.

Note that the Istio Helm chart values are under active development and considered experimental. Upgrading to newer versions of Istio can involve migrating your override values to follow the new API.

For customizations that are supported via both ProxyConfig and Helm values, using ProxyConfig is recommended because it provides schema validation while unstructured Helm values do not.

Upgrading using Helm

Before upgrading Istio in your cluster, we recommend creating a backup of your custom configurations, and restoring it from backup if necessary:

$ kubectl get crds | grep 'istio.io' | cut -f1-1 -d "." | \ xargs -n1 -I{} sh -c "kubectl get --all-namespaces -o yaml {}; echo ---" > $HOME/ISTIO_RESOURCE_BACKUP.yaml

You can restore your custom configuration like this:

$ kubectl apply -f $HOME/ISTIO_RESOURCE_BACKUP.yaml

Migrating from non-Helm installations

If you’re migrating from a version of Istio installed using istioctl or Operator to Helm, you need to delete your current Istio control plane resources and and re-install Istio using Helm as described above. When deleting your current Istio installation, you must not remove the Istio Custom Resource Definitions (CRDs) as that can lead to loss of your custom Istio resources.

It is highly recommended to take a backup of your Istio resources using steps described above before deleting current Istio installation in your cluster.

You can follow steps mentioned in the Istioctl uninstall guide or Operator uninstall guide depending upon your installation method.

Canary upgrade (recommended)

You can install a canary version of Istio control plane to validate that the new version is compatible with your existing configuration and data plane using the steps below:

Note that when you install a canary version of the istiod service, the underlying cluster-wide resources from the base chart are shared across your primary and canary installations.

Currently, there is no support for canary upgrades for Istio ingress and egress gateways.

Install a canary version of the Istio discovery chart by setting the revision value:

$ helm install --namespace istio-system istiod-canary manifests/charts/istio-control/istio-discovery --set revision=canary \ --set global.hub="docker.io/istio" --set global.tag=<version_to_upgrade>
Verify that you have two versions of istiod installed in your cluster:

$ kubectl get pods -n istio-system -l app=istiod -L istio.io/rev NAME READY STATUS RESTARTS AGE REV istiod-5649c48ddc-dlkh8 1/1 Running 0 71m default istiod-canary-9cc9fd96f-jpc7n 1/1 Running 0 34m canary
Follow the steps here to test or migrate existing workloads to use the canary control plane.
Once you have verified and migrated your workloads to use the canary control plane, you can uninstall your old control plane:

$ helm delete --namespace istio-system istiod

In place upgrade

You can perform an in place upgrade of Istio in your cluster using the Helm upgrade workflow.

This upgrade path is only supported from Istio version 1.8 and above.

Add your override values file or custom options to the commands below to preserve your custom configuration during Helm upgrades.

Upgrade the Istio base chart:

$ helm upgrade --namespace istio-system istio-base manifests/charts/base
Upgrade the Istio discovery chart:

$ helm upgrade --namespace istio-system istiod manifests/charts/istio-control/istio-discovery \ --set global.hub="docker.io/istio" --set global.tag="<version_to_upgrade>"
(Optional) Upgrade the Istio ingress or egress gateway charts if installed in your cluster:

$ helm upgrade --namespace istio-system istio-ingress manifests/charts/gateways/istio-ingress \ --set global.hub="docker.io/istio" --set "global.tag=<version_to_upgrade>" $ helm upgrade --namespace istio-system istio-egress manifests/charts/gateways/istio-egress \ --set global.hub="docker.io/istio" --set "global.tag=<version_to_upgrade>"

Uninstall

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

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

$ helm ls --namespace istio-system
(Optional) Delete Istio ingress/egress chart:

$ helm delete --namespace istio-system istio-egress $ helm delete --namespace istio-system istio-ingress
Delete Istio discovery chart:

$ helm delete --namespace istio-system istiod
Delete Istio base chart:

By design, deleting a chart via Helm doesn’t delete the installed Custom Resource Definitions (CRDs) installed via the chart.

$ helm delete --namespace istio-system istio-base
Delete the istio-system namespace:

$ kubectl delete namespace istio-system