Install sidecar service meshes with Helm

Before you begin link

1. Install Gloo Mesh Core by following the single cluster getting started guide or the Helm single cluster setup guide. Do not install Istio as part of your setup.

2. Be sure to review the following known Istio version restrictions.

   warning

   In Istio 1.22.0-1.22.3, the ISTIO_DELTA_XDS environment variable must be set to false. For more information, see this upstream Istio issue. Note that this issue is resolved in Istio 1.22.4.
   
   In Gloo Mesh Core version 2.6, ambient mode requires the Solo distribution of Istio version 1.22.3 or later (1.22.3-solo).
   
   

   Istio 1.20 is supported only as patch version 1.20.1-patch1 and later. Do not use patch versions 1.20.0 and 1.20.1, which contain bugs that impact several Gloo Mesh Core features that rely on Istio ServiceEntries.

Step 1: Set up tools link

Set up the following tools and environment variables.

1. Review Supported versions to choose the Solo distribution of Istio that you want to use, and save the version information in the following environment variables.

   • REPO: The repo key for the Solo distribution of Istio that you can get by logging in to the Support Center and reviewing the Istio images built by Solo.io support article.
   • ISTIO_IMAGE: The version that you want to use with the solo tag, such as 1.24.2-solo. You can optionally append other tags of Solo distributions of Istio as needed.
   • REVISION: Take the Istio major and minor versions and replace the periods with hyphens, such as 1-24.
   • ISTIO_VERSION: The version of Istio that you want to install, such as 1.24.2.

     export REPO=<repo-key>
   export ISTIO_IMAGE=1.24.2-solo
   export REVISION=1-24
   export ISTIO_VERSION=1.24.2
     

2. Install istioctl, the Istio CLI tool.

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

3. Add and update the Helm repository for Istio.

     helm repo add istio https://istio-release.storage.googleapis.com/charts
   helm repo update
     

Step 2: Prepare the cluster environment link

Prepare the workload cluster for Istio installation, including installing the Istio custom resource definitions (CRDs).

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=<remote-cluster>
   export REMOTE_CONTEXT=<remote-cluster-context>
     

2. Ensure that the Istio operator CRD (istiooperators.install.istio.io) is not managed by the Gloo Platform CRD Helm chart.

     kubectl get crds -A --context $REMOTE_CONTEXT | grep istiooperators.install.istio.io
     

   • If the CRD does not exist on your cluster, you disabled it during the Gloo Mesh installation. Continue to the next step.
   • If the CRD exists on your cluster, follow these steps to remove the Istio operator CRD from the gloo-platform-crds Helm release:
     1. Update the Helm repository for Gloo Platform.

          helm repo add gloo-platform https://storage.googleapis.com/gloo-platform/helm-charts
        helm repo update
          

     2. Upgrade your gloo-platform-crds Helm release in the workload cluster by including the --set installIstioOperator=false flag.

          helm upgrade gloo-platform-crds gloo-platform/gloo-platform-crds \
           --kube-context $REMOTE_CONTEXT \
           --namespace=gloo-mesh \
           --set installIstioOperator=false
          

3. Install the Istio CRDs.

     helm upgrade --install istio-base istio/base \
     -n istio-system \
     --version $ISTIO_VERSION \
     --kube-context $REMOTE_CONTEXT \
     --create-namespace
     

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

5. OpenShift only:

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

        helm install istio-cni istio/cni \
      --namespace kube-system \
      --kube-context $REMOTE_CONTEXT \
      --version $ISTIO_VERSION \
      --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
        

Step 3: Deploy the Istio control plane link

Deploy an Istio control plane in your workload cluster. 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.

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.

        curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/manual-helm/istiod.yaml > istiod.yaml
      envsubst < istiod.yaml > 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.

      info

      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. For more information, see Multiple Istio revisions in the same cluster.

2. Create the istiod control plane in your cluster.

     helm upgrade --install istiod-$REVISION istio/istiod \
     --version $ISTIO_VERSION \
     --namespace istio-system \
     --kube-context $REMOTE_CONTEXT \
     --wait \
     -f istiod-values.yaml
     

     helm upgrade --install istiod-$REVISION istio/istiod \
     --version $ISTIO_VERSION \
     --namespace istio-system \
     --kube-context $REMOTE_CONTEXT \
     --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 --context $REMOTE_CONTEXT
     

   Example output for 2 replicas:

     NAME                          READY   STATUS    RESTARTS   AGE
   istiod-1-24-7b96cb895-4nzv9   1/1     Running   0          30s
   istiod-1-24-7b96cb895-r7l8k   1/1     Running   0          30s
     

Multicluster setups: Repeat steps 2 - 3 link

If you have a multicluster setup, repeat steps 2 - 3 for each workload cluster that you want to install Istio in. Remember to change the cluster name and context variables each time you repeat the steps.

  export CLUSTER_NAME=<remote-cluster>
export REMOTE_CONTEXT=<remote-cluster-context>
  

Next link

Add apps to the service mesh.