Helm

For more information about the components that are installed in these steps, see the ambient components overview.

Considerations link

Before you install an ambient mesh, review the following considerations and requirements.

Version requirements

Review the following known Istio version requirements and restrictions.

• Patch versions 1.26.0 and 1.26.1 of the Solo distribution of Istio lack support for FIPS-tagged images and ztunnel outlier detection. 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.
• Multicluster setups require the Solo distribution of Istio version 1.24.3 or later (1.24.3-solo), including the Solo distribution of istioctl.
• Due to a lack of support for the Istio CNI and iptables for the Istio proxy, you cannot run Istio (and therefore Gloo Mesh (OSS APIs)) on AWS Fargate. For more information, see the Amazon EKS issue.

Single-cluster and multicluster meshes

This guide shows you how to install an ambient mesh in one cluster. If you later decide to to upgrade to a multicluster mesh with an Enterprise level license, you can link your existing ambient meshes across clusters.

Alternatively, if you prefer to start with a multicluster mesh immediately, check out Install and connect new ambient meshes in the multicluster guide instead.

Platform requirements

The steps in the following sections have options for deploying an ambient mesh to either Kubernetes or OpenShift clusters.

If you use OpenShift clusters, complete the following steps before you begin:

• Set routingViaHost: true in the Cluster Network Operator to enable OVN-Kubernetes local gateway mode. For more information, see the Platform-specific prerequisites in the ambient mesh docs.

The commands for OpenShift in the following steps contain these required settings:

• Your Helm settings must include global.platform=openshift for Istio 1.24 and later. If you instead install Istio 1.23 or earlier, you must use profile=openshift instead of the global.platform setting.
• Install the istio-cni and ztunnel Helm releases in the kube-system namespace, instead of the istio-system namespace.

Revision and canary upgrade limitations

The upgrade guides in this documentation show you how to perform in-place upgrades for your Istio components, which is the recommended upgrade strategy.

Step 1: Set up tools link

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.

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.28.0
      # 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 version 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 version 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 SOLO_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
     

6. Check the platform-specific prerequisites for ambient to determine whether you must make any changes to your environment before you install an ambient mesh.

Step 2: Install CRDs link

1. Apply the CRDs for the Kubernetes Gateway API to your cluster, which are required to create components such as waypoint proxies for L7 traffic policies, gateways with the Gateway resource, and more.

     kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml
     

2. Install the base chart, which contains the CRDs and cluster roles required to set up Istio.

     helm upgrade --install istio-base oci://${HELM_REPO}/base \
   --namespace istio-system \
   --create-namespace \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   defaultRevision: ""
   profile: ambient
   EOF
     

     helm upgrade --install istio-base oci://${HELM_REPO}/base \
   --namespace istio-system \
   --create-namespace \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   defaultRevision: ""
   profile: ambient
   global:
     platform: openshift
   EOF
     

Step 3: Deploy the ambient control plane link

1. Create the istiod control plane in your cluster.

     helm upgrade --install istiod oci://${HELM_REPO}/istiod \
   --namespace istio-system \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   global:
     hub: ${REPO}
     proxy:
       clusterDomain: cluster.local
     tag: ${ISTIO_IMAGE}
   meshConfig:
     accessLogFile: /dev/stdout
     defaultConfig:
       proxyMetadata:
         ISTIO_META_DNS_AUTO_ALLOCATE: "true"
         ISTIO_META_DNS_CAPTURE: "true"
   env:
     PILOT_ENABLE_IP_AUTOALLOCATE: "true"
     PILOT_ENABLE_K8S_SELECT_WORKLOAD_ENTRIES: "false"
     PILOT_SKIP_VALIDATE_TRUST_DOMAIN: "true"
   pilot:
     cni:
       namespace: istio-system
       enabled: true
   profile: ambient
   license:
     value: ${SOLO_LICENSE_KEY}
     # Uncomment if you prefer to specify your license secret
     # instead of an inline value.
     # secretRef:
     #   name: 
     #   namespace: 
   EOF
     

     helm upgrade --install istiod oci://${HELM_REPO}/istiod \
   --namespace istio-system \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   global:
     hub: ${REPO}
     platform: openshift
     proxy:
       clusterDomain: cluster.local
     tag: ${ISTIO_IMAGE}
   pilot:
     cni:
       namespace: kube-system
       enabled: true
   meshConfig:
     accessLogFile: /dev/stdout
     defaultConfig:
       proxyMetadata:
         ISTIO_META_DNS_AUTO_ALLOCATE: "true"
         ISTIO_META_DNS_CAPTURE: "true"
   env:
     PILOT_ENABLE_IP_AUTOALLOCATE: "true"
     PILOT_ENABLE_K8S_SELECT_WORKLOAD_ENTRIES: "false"
     PILOT_SKIP_VALIDATE_TRUST_DOMAIN: "true"
   profile: ambient
   license:
     value: ${SOLO_LICENSE_KEY}
     # Uncomment if you prefer to specify your license secret
     # instead of an inline value.
     # secretRef:
     #   name: 
     #   namespace: 
   EOF
     

2. Install the Istio CNI node agent daemonset. Note that although the CNI is included in this section, it is technically not part of the control plane or data plane.

     helm upgrade --install istio-cni oci://${HELM_REPO}/cni \
   --namespace istio-system \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   ambient:
     dnsCapture: true
   excludeNamespaces:
     - istio-system
     - kube-system
   global:
     hub: ${REPO}
     tag: ${ISTIO_IMAGE}
   profile: ambient
   EOF
     

     helm upgrade --install istio-cni oci://${HELM_REPO}/cni \
   --namespace kube-system \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   ambient:
     dnsCapture: true
   excludeNamespaces:
     - istio-system
     - kube-system
   global:
     hub: ${REPO}
     platform: openshift
     tag: ${ISTIO_IMAGE}
   profile: ambient
   EOF
     

3. Verify that the components of the Istio ambient control plane are successfully installed. Because the Istio CNI is deployed as a daemon set, the number of CNI pods equals the number of nodes in your cluster. Note that it might take a few seconds for the pods to become available.

     kubectl get pods -A | grep istio
     

   Example output:

     istio-system   istiod-85c4dfd97f-mncj5                             1/1     Running   0               40s
   istio-system   istio-cni-node-pr5rl                                1/1     Running   0               9s
   istio-system   istio-cni-node-pvmx2                                1/1     Running   0               9s
   istio-system   istio-cni-node-6q26l                                1/1     Running   0               9s
     

Step 4: Deploy the ambient data plane link

1. Install the ztunnel daemonset.

     helm upgrade --install ztunnel oci://${HELM_REPO}/ztunnel \
   --namespace istio-system \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   configValidation: true
   enabled: true
   env:
     L7_ENABLED: "true"
   hub: ${REPO}
   istioNamespace: istio-system
   namespace: istio-system
   profile: ambient
   proxy:
     clusterDomain: cluster.local
   tag: ${ISTIO_IMAGE}
   terminationGracePeriodSeconds: 29
   variant: distroless
   EOF
     

     helm upgrade --install ztunnel oci://${HELM_REPO}/ztunnel \
   --namespace kube-system \
   --version ${ISTIO_IMAGE} \
   -f - <<EOF
   configValidation: true
   enabled: true
   env:
     L7_ENABLED: "true"
   global:
     platform: openshift
   hub: ${REPO}
   istioNamespace: istio-system
   namespace: kube-system
   profile: ambient
   proxy:
     clusterDomain: cluster.local
   tag: ${ISTIO_IMAGE}
   terminationGracePeriodSeconds: 29
   variant: distroless
   EOF
     

2. Verify that the ztunnel pods are successfully installed. Because the ztunnel is deployed as a daemon set, the number of pods equals the number of nodes in your cluster. Note that it might take a few seconds for the pods to become available.

     kubectl get pods -A | grep ztunnel
     

   Example output:

     ztunnel-tvtzn             1/1     Running   0          7s
   ztunnel-vtpjm             1/1     Running   0          4s
   ztunnel-hllxg             1/1     Running   0          4s
     

Next link

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