Install with Helm [Experimental]

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

Prerequisites

1. Download the Istio release.

2. Perform any necessary platform-specific setup⁶.

3. Check the Requirements for Pods and Services⁷.

4. Install a Helm client⁸ with a version higher than 3.1.1.

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.

1. Create a namespace istio-system for Istio components:

   $ kubectl create namespace istio-system
   

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

3. Install the Istio discovery chart which deploys the istiod service:

   $ helm install --namespace istio-system istiod manifests/charts/istio-control/istio-discovery
   

4. (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
   

5. (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
   

Verifying the installation

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

   $ kubectl get pods -n istio-system
   

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 installation and re-install Istio using Helm as described above.

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

In place upgrade

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

1. Upgrade the Istio base chart:

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

2. Upgrade the Istio discovery chart:

   $ helm upgrade --namespace istio-system istiod manifests/charts/istio-control/istio-discovery
   

3. (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
   $ helm upgrade --namespace istio-system istio-egress manifests/charts/gateways/istio-egress
   

Canary Upgrade

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:

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

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

3. Follow the steps here to test or migrate existing workloads to use the canary control plane.

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

Uninstall

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

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

   $ helm ls --namespace istio-system
   

2. (Optional) Delete Istio ingress/egress chart:

   $ helm delete --namespace istio-system istio-egress
   $ helm delete --namespace istio-system istio-ingress
   

3. Delete Istio discovery chart:

   $ helm delete --namespace istio-system istiod
   

4. Delete Istio base chart:

   $ helm delete --namespace istio-system istio-base
   

5. Delete the istio-system namespace:

   $ kubectl delete namespace istio-system
   

Deleting CRDs installed by Istio

Deleting CRDs permanently removes any Istio resources you have created in your cluster. To permanently delete Istio CRDs installed in your cluster:

$ kubectl get crd | grep --color=never 'istio.io' | awk '{print $1}' \
    | xargs -n1 kubectl delete crd