Install Istio in ambient mode

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

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

Single-cluster limitation

In Istio versions 1.23 and earlier, Istio in ambient mode is supported only for single clusters. Ambient mode in a multicluster environment where apps in different clusters can communicate through east-west routing as part of a single service mesh is not supported. However, you can still deploy separate ambient service meshes to multiple, individual workload clusters.

Multicluster routing with an ambient mesh is supported in the Solo distribution Istio 1.24 and later. To try it out, consider upgrading to Gloo Mesh version 2.7, which includes support for Istio 1.24.

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. Set environment variables for the Solo distribution of Istio that you want to install. You can find these values in the Istio images built by Solo.io support article. For more information, see the Solo distribution of Istio overview.

     # Solo distrubution of Istio patch version
   # in the format 1.x.x, with no tags
   export ISTIO_VERSION=1.23.4
   # Repo key for the minor version of the Solo distribution of Istio
   # This is the 12-character hash at the end of the repo URL: 'us-docker.pkg.dev/gloo-mesh/istio-<repo-key>'
   export REPO_KEY=<repo_key>
   # Solo distrubution of Istio patch version and Solo tag
   # Optionally append other Solo tags as needed
   export ISTIO_IMAGE=${ISTIO_VERSION}-solo
   # Solo distribution of Istio image repo
   export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
   # Solo distribution of Istio Helm repo
   export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}
     

2. Install istioctl, the Istio command line tool. Use the same version that you want to use to install your ambient mesh.

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

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

   Istio 1.25 and later: If you prefer to specify your license secret instead of an inline value, you can uncomment the secretRef fields.

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

     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}
   istio_cni:
     namespace: istio-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: ${LICENSE_KEY}
     # secretRef:
     #   name: 
     #   namespace: 
   EOF
     

   Istio 1.24 and earlier:

     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}
   istio_cni:
     namespace: istio-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
   EOF
     

   Istio 1.25 and later: If you prefer to specify your license secret instead of an inline value, you can uncomment the secretRef fields.

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

     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}
   istio_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: ${LICENSE_KEY}
     # secretRef:
     #   name: 
     #   namespace: 
   EOF
     

   Istio 1.24 and earlier:

     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}
   istio_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
   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
     

3. Optional: To send requests to sample apps from outside your Gloo Mesh setup, you can deploy an Istio ingress gateway.

   1. Create the istio-ingress namespace. Note that you might choose a different namespace, such as istio-gateways. If so, be sure to change the namespace in subsequent steps.

        kubectl create ns istio-ingress
        

   2. Create a Kubernetes service to expose the ingress gateway.

        kubectl apply -f - <<EOF
      apiVersion: v1
      kind: Service
      metadata:
        labels:
          app: istio-ingressgateway
          istio: ingressgateway
        name: istio-ingressgateway
        namespace: istio-ingress
      spec:
        ports:
        - name: http2
          port: 80
          protocol: TCP
          targetPort: 80
        - name: https
          port: 443
          protocol: TCP
          targetPort: 443
        selector:
          app: istio-ingressgateway
          istio: ingressgateway
        type: LoadBalancer
      EOF
        

   3. Deploy the Istio ingress gateway.

        helm upgrade --install istio-ingressgateway oci://${HELM_REPO}/gateway \
      --namespace istio-ingress \
      --version ${ISTIO_IMAGE} \
      -f - <<EOF
      autoscaling:
        enabled: false
      imagePullPolicy: IfNotPresent
      profile: ambient
      labels:
        app: istio-ingressgateway
        istio: ingressgateway
      service:
        type: None
      EOF
        

   4. Verify that the ingress gateway pod has a status of RUNNING and that the load balancer service has an external address.

        kubectl get pods,svc -n istio-ingress
        

      Example output:

        NAME                                    READY   STATUS    RESTARTS   AGE
      istio-ingressgateway-665d46686f-nhh52   1/1     Running   0          106s
      
      NAME                        TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                                                      AGE
      istio-ingressgateway        LoadBalancer   10.96.252.49    <externalip>  15021:32378/TCP,80:30315/TCP,443:32186/TCP,31400:30313/TCP,15443:31632/TCP                                   2m2s
        

Next link

Deploy sample apps and add them to the ambient mesh.