Overview

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

Prepare the cluster environment

Set up the following tools and environment variables.

  1. If you do not already have a license, contact an account representative.

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

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

  4. Save the details for the version of the Solo distribution of Istio that you want to install.

    1. Save the details for version 1.25 of the Solo distribution of Istio.
        export ISTIO_VERSION=1.25.2
# Change the tags as needed
export ISTIO_IMAGE=${ISTIO_VERSION}-solo
export REPO_KEY=e038d180f90a
export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}
    2. Optional: Set your license key as an environment variable. If you do not have one, contact an account representative. If you prefer to specify license keys in a secret instead, see Licensing.
        export GLOO_MESH_LICENSE_KEY=<enterprise_license_key>
    1. Save the Solo distribution of Istio patch version and tag.
        export ISTIO_VERSION=1.24.5
# Change the tags as needed
export ISTIO_IMAGE=${ISTIO_VERSION}-solo
    2. 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 Ambient section of 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}

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

  1. Save the name and kubeconfig context of a workload cluster in the following environment variables. Each time you repeat the steps in this guide, you change these variables to the next workload cluster’s name and context.

      export CLUSTER_NAME=<cluster-name>
export CLUSTER_CONTEXT=<cluster-context>

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

  3. 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}

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

  5. 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/gloo-mesh-use-cases/main/gloo-mesh-enterprise/istio-install/manual-helm/istiod-1.24+.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.

  6. Create the istiod control plane in your cluster.

    • Istio 1.25 and later: 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}
    • Istio 1.24 and earlier:
        helm upgrade --install istiod oci://${HELM_REPO}/istiod \
  --version ${ISTIO_IMAGE} \
  --namespace istio-system \
  --kube-context ${CLUSTER_CONTEXT} \
  --wait \
  -f istiod-values.yaml
    • Istio 1.25 and later: 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}
    • Istio 1.24 and earlier: If you install Istio 1.23 or earlier, you must use --set profile=openshift instead of the global.platform setting.
        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

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

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

Next