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, decide the level of licensed features that you want, and contact an account representative to obtain the license.

  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 Solo distribution of Istio patch version and tag.
        export ISTIO_VERSION=1.26.2
# 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 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 LICENSE_KEY=<license_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

Install CRDs

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

  1. Save the name of a workload cluster in the following environment variable.

      export CLUSTER_NAME=<cluster-name>

  2. Install the Istio CRDs.

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

  3. Create the istio-config namespace. This namespace serves as the administrative root namespace for Istio configuration.

      kubectl create namespace istio-config

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

Install the Istio control plane

  1. 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. 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 \
  --wait \
  -f istiod-values.yaml \
  --set license.value=${LICENSE_KEY}
  
      helm upgrade --install istiod istiod/istiod \
  --version ${ISTIO_VERSION} \
  --namespace istio-system \
  --wait \
  -f istiod-values.yaml \
  --set pilot.env.SOLO_LICENSE_KEY=${LICENSE_KEY}

    Istio 1.24 and earlier:

      helm upgrade --install istiod oci://${HELM_REPO}/istiod \
  --version ${ISTIO_IMAGE} \
  --namespace istio-system \
  --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 \
  --wait \
  -f istiod-values.yaml \
  --set global.platform=openshift \
  --set license.value=${LICENSE_KEY}
  
      helm upgrade --install istiod istiod/istiod \
  --version ${ISTIO_VERSION} \
  --namespace istio-system \
  --wait \
  -f istiod-values.yaml \
  --set global.platform=openshift \
 --set pilot.env.SOLO_LICENSE_KEY=${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 \
  --wait \
  -f istiod-values.yaml \
  --set global.platform=openshift

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

      kubectl get pods -n istio-system

    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

Next