On this page

Manually install an ambient mesh with Helm

Use Helm to deploy an ambient service mesh to your Gloo Mesh cluster.

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

Considerations

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).
If you plan to later link meshes for a multicluster ambient mesh setup: In Gloo Mesh version 2.7 and later, multicluster setups require version 1.24.3 or later.
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 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.

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

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.
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).
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.
Save the details for the version of the Solo distribution of Istio that you want to install.
Istio 1.25 Istio 1.24 and earlier
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.
1. 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
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 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}

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

Step 2: Install CRDs

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.2.1/standard-install.yaml
  
```

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

If you use Google Kubernetes Engine (GKE) clusters, create the following ResourceQuota in the istio-system namespace of each cluster. For more information about this requirement, see the community Istio documentation.

  kubectl create namespace istio-system
kubectl -n istio-system apply -f - <<EOF
apiVersion: v1
kind: ResourceQuota
metadata:
  name: gcp-critical-pods
  namespace: istio-system
spec:
  hard:
    pods: 1000
  scopeSelector:
    matchExpressions:
    - operator: In
      scopeName: PriorityClass
      values:
      - system-node-critical
EOF

Step 3: Deploy the ambient control plane

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.

  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: ${GLOO_MESH_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.

  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: ${GLOO_MESH_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

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

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

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

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

Manually install an ambient mesh with Helm

Considerations link

Step 1: Set up tools link

Step 2: Install CRDs link

Step 3: Deploy the ambient control plane link

Step 4: Deploy the ambient data plane link

Next link

Considerations

Step 1: Set up tools

Step 2: Install CRDs

Step 3: Deploy the ambient control plane

Step 4: Deploy the ambient data plane

Next