Manually install a sidecar mesh with Helm

Overview link

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.
• This guide shows you how to install a sidecar mesh in one cluster. To install a multicluster mesh instead, check out Create a multicluster mesh with Helm instead.

Prepare the cluster environment link

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. In Gloo Mesh version 2.6 and later, ambient mode requires the Solo distribution of Istio version 1.22.3 or later (1.22.3-solo).

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>
        

   notifications

   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 your Solo istiod Helm chart. The Helm chart that is provided by Solo includes safeguards, default settings, and upgrade handling to ensure a reliable and secure Istio deployment. Although you can pass the license key in the pilot.env.SOLO_LICENSE_KEY field of the open source Istio Helm chart, this method is not recommended. For best results, we strongly recommend using the Solo Helm chart to install and manage Istio. For example, to install the Solo distribution of 1.25, you can run the helm install istiod oci://us-docker.pkg.dev/gloo-mesh/istio-helm-e038d180f90a/istiod ... command and provide your installation values in --set flags or a -f <file.yaml> config file.

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

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

Install CRDs link

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 link

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=${GLOO_MESH_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=${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 \
       --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 link

• Add apps to the service mesh.
• Link meshes together to create a multicluster mesh.