Install Istio service meshes with Helm

Use Istio Helm charts to configure and deploy an Istio control plane and gateways in each workload cluster.

Overview

Review the following information about the Istio control plane setup in this guide:

This installation guide installs a production-level Solo distribution of Istio, a hardened Istio enterprise image. For more information, see About the Solo distribution of Istio.
For more information about using Istio Helm charts, see the Istio documentation.
- For information about the namespaces that are used in this guide and other deployment recommendations, see Best practices for Istio in prod.

Set up tools

Set up the following tools and environment variables.

If you do not already have a license, contact an account representative.
Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions table. Be sure to review the following known Istio version restrictions.
- The JWT policy translator serializes workload-key identifiers using a "." delimiter. If a gateway pod carries labels with dots in the key name (for example, app.kubernetes.io/name), the serialization produces an ambiguous key that breaks label-selector matching. Affected JWT authentication policies fail open, meaning requests that should be rejected based on JWT claims are allowed through without authentication. As a workaround, use dot-free label keys on gateway pods that are targeted by JWT authentication policies. For example, replace app.kubernetes.io/name: my-gateway with app: my-gateway as the selector label. This issue is resolved in Gloo Mesh Enterprise 2.14.
- If you use Istio versions 1.27.7, 1.28.4, 1.29.0 or later, and you install the Gloo Mesh (Gloo Platform APIs) management plane (Gloo UI) into a namespace other than gloo-mesh, you must allow that namespace by listing it in the DEBUG_ENDPOINT_AUTH_ALLOWED_NAMESPACES environment variable of your istiod installation. For more information, see the release notes.
- Patch versions 1.26.0 and 1.26.1 of the Solo distribution of Istio lack support for FIPS-tagged images. When upgrading or installing 1.26, be sure to use patch version 1.26.1-patch0 and later only.
- In the Solo distribution of Istio 1.25 and later, you can access enterprise-level features by passing your Solo license in the license.value or license.secretRef field of the Solo distribution of the istiod Helm chart. The Solo istiod Helm chart is strongly recommended due to the included safeguards, default settings, and upgrade handling to ensure a reliable and secure Istio deployment. Though it is not recommended, you can pass your license key in the open source istiod Helm chart by using the --set pilot.env.SOLO_LICENSE_KEY field.
- Istio patch versions 1.25.1 and 1.24.4 contain an upstream certificate rotation bug in which requests with more than one trusted root certificate cannot be validated. If you use Gloo Mesh (Gloo Platform APIs) to manage root certificate rotation and use Istio 1.25 or 1.24, be sure to use 1.25.2 or 1.24.5 and later only.
- Due to a lack of support for the Istio CNI and iptables for the Istio proxy, you cannot run Istio (and therefore Gloo Mesh (Gloo Platform APIs)) on AWS Fargate. For more information, see the Amazon EKS issue.
Decide on the specific tag of Solo distribution of Istio image, such as -solo, -solo-fips, -solo-distroless, or -solo-fips-distroless, that you want for your environment.
Save the details for the version of the Solo distribution of Istio that you want to install.
1. Save the Solo distribution of Istio patch version and tag.
  export ISTIO_VERSION=1.30.21.29.5 # Change the tags as needed export ISTIO_IMAGE=${ISTIO_VERSION}-solo
2. Save the image and Helm repository information for the Solo distribution of Istio.
  - Istio 1.29 and later:
    export REPO=us-docker.pkg.dev/soloio-img/istio export HELM_REPO=us-docker.pkg.dev/soloio-img/istio-helm
  - Istio 1.28 and earlier: Save the repo key for the minor version of the Solo distribution of Istio that you want to install. This is the 12-character hash at the end of the repo URL us-docker.pkg.dev/gloo-mesh/istio-<repo-key>, which you can find in the Istio images built by Solo.io support article.
    # 12-character hash at the end of the minor version repo URL export REPO_KEY=<repo_key> export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY} export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}
3. Set your license key as an environment variable. If you prefer to specify license keys in a secret instead, see Licensing.
  export GLOO_MESH_LICENSE_KEY=<enterprise_license_key>

Install or upgrade istioctl with the same version of Istio that you saved.

curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
cd istio-${ISTIO_VERSION}
export PATH=$PWD/bin:$PATH

Deploy an Istio service mesh with Helm

Deploy the Istio CRDs and a sidecar control plane to your cluster.

Save the name and kubeconfig context of a cluster in the following environment variables. Each time you repeat the steps in this guide, you change these variables to the next cluster’s name and context.
```
export CLUSTER_NAME=<cluster-name>
export CLUSTER_CONTEXT=<cluster-context>
```

Install the Istio CRDs.

helm upgrade --install istio-base oci://${HELM_REPO}/base \
  -n istio-system \
  --create-namespace \
  --kube-context ${CLUSTER_CONTEXT} \
  --version ${ISTIO_IMAGE} \
  --set defaultRevision=main

Create the istio-config namespace. This namespace serves as the administrative root namespace for Istio configuration. For more information, see Plan Istio namespaces.
```
kubectl create namespace istio-config --context ${CLUSTER_CONTEXT}
```

OpenShift only: Install the CNI plug-in, which is required for using Istio in OpenShift.

helm install istio-cni oci://${HELM_REPO}/cni \
--namespace kube-system \
--kube-context ${CLUSTER_CONTEXT} \
--version ${ISTIO_IMAGE} \
--set cni.cniBinDir=/var/lib/cni/bin \
--set cni.cniConfDir=/etc/cni/multus/net.d \
--set cni.cniConfFileName="istio-cni.conf" \
--set cni.chained=false \
--set cni.privileged=true \
--set global.platform=openshift

Prepare a Helm values file for the istiod control plane. You can further edit the file to provide your own details for production-level settings.
1. Download an example file, istiod.yaml, and update the environment variables with the values that you previously set. The provided Helm values files are configured with production-level settings; however, depending on your environment, you might need to edit settings to achieve specific Istio functionality.
  curl -0L https://raw.githubusercontent.com/solo-io/doc-examples/main/istio/sidecar/istiod.yaml > istiod.yaml envsubst < istiod.yaml > istiod-values.yaml open istiod-values.yaml
2. Optional: Trust domain validation is disabled by default in the profile that you downloaded in the previous step. If you have a multicluster mesh setup and you want to enable trust domain validation, add all the clusters that are part of your mesh in the meshConfig.trustDomainAliases field, excluding the cluster that you currently prepare for the istiod installation. For example, let’s say you have 3 clusters that belong to your mesh: cluster1, cluster2, and cluster3. When you install istiod in cluster1, you set the following values for your trust domain:
  ... meshConfig: trustDomain: cluster1 trustDomainAliases: ["cluster2","cluster3"]
  Then, when you move on to install istiod in cluster2, you set trustDomain: cluster2 and trustDomainAliases: ["cluster1","cluster3"]. You repeat this step for all the clusters that belong to your service mesh. Note that as you add or delete clusters from your service mesh, you must make sure that you update the trustDomainAliases field for all of the clusters.
  If you plan to run multiple revisions of Istio in your cluster and use discoverySelectors in each revision to discover the resources in specific namespaces, enable the glooMgmtServer.extraEnvs.IGNORE_REVISIONS_FOR_VIRTUAL_DESTINATION_TRANSLATION environment variable on the Gloo management server.
Create the istiod control plane in your cluster.
If you prefer to specify your license secret instead of an inline value, you can include --set license.secretRef.name=<name> and --set license.secretRef.namespace=<namespace>.
helm upgrade --install istiod oci://${HELM_REPO}/istiod \ --version ${ISTIO_IMAGE} \ --namespace istio-system \ --kube-context ${CLUSTER_CONTEXT} \ --wait \ -f istiod-values.yaml \ --set license.value=${GLOO_MESH_LICENSE_KEY}
If you prefer to specify your license secret instead of an inline value, you can include --set license.secretRef.name=<name> and --set license.secretRef.namespace=<namespace>.
helm upgrade --install istiod oci://${HELM_REPO}/istiod \ --version ${ISTIO_IMAGE} \ --namespace istio-system \ --kube-context ${CLUSTER_CONTEXT} \ --wait \ -f istiod-values.yaml \ --set global.platform=openshift \ --set license.value=${GLOO_MESH_LICENSE_KEY}
In the Solo distribution of Istio 1.25 and later, you can access enterprise-level features by passing your Solo license in the license.value or license.secretRef field of the Solo distribution of the istiod Helm chart. The Solo istiod Helm chart is strongly recommended due to the included safeguards, default settings, and upgrade handling to ensure a reliable and secure Istio deployment. Though it is not recommended, you can pass your license key in the open source istiod Helm chart by using the –set pilot.env.SOLO_LICENSE_KEY field.
helm upgrade --install istiod istiod/istiod \ --version ${ISTIO_VERSION} \ --namespace istio-system \ --kube-context ${CLUSTER_CONTEXT} \ --wait \ -f istiod-values.yaml \ --set global.platform=openshift \ --set pilot.env.SOLO_ISTIO_LICENSE_KEY=${GLOO_MESH_LICENSE_KEY}

After the installation is complete, verify that the Istio control plane pods are running.

kubectl get pods -n istio-system --context ${CLUSTER_CONTEXT}

Example output:

NAME                          READY   STATUS    RESTARTS   AGE
istiod-main-bb86b959f-msrg7   1/1     Running   0          2m45s
istiod-main-bb86b959f-w29cm   1/1     Running   0          3m

Multicluster setups: Repeat steps 1 - 7 for each cluster where you want to install Istio. Be sure to change the values of the $CLUSTER_NAME and $CLUSTER_CONTEXT environment variables for each cluster.

Add apps to the service mesh.
For multicluster environments, deploy east-west gateways to your clusters.

Best practices for Istio in prod Upgrade Istio service meshes with Helm

Install Istio service meshes with Helm

Overview

Set up tools

Deploy an Istio service mesh with Helm

Next