On this page

Install Istio in ambient mode

Use the Solo distribution of Istio to deploy Istio in ambient mode.

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

Considerations

Before you install Istio in ambient mode, review the following considerations and requirements.

Version requirements

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

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

Revision and canary upgrade limitations

Revisioned upgrades are supported only for the istiod control plane and Istio gateways in ambient installations. Due to an upstream ambient limitation, the ztunnel and Istio CNI pods do not support revisioned canary upgrades, and can only be upgraded in-place. For this reason, creating named revisions for the istiod, cni, ztunnel, and gateways in an ambient mesh is not currently recommended.

Before you begin

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.

If you use Google Kubernetes Engine (GKE) clusters, create the following ResourceQuota in the istio-system namespace. 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

Install CRDs

Set environment variables for the Solo distribution of Istio that you want to install, including the image version, image repository, and Helm repository. You can find these values in the Ambient section of the Istio images built by Solo.io support article.

  # Solo distrubution of Istio patch version and tag, in the format 1.x.x-solo
export ISTIO_IMAGE=1.22.5-patch0-solo
# Solo distrubution of Istio repo
export REPO=us-docker.pkg.dev/gloo-mesh/istio-<repo-key>
# Solo distrubution of Istio Helm repo
export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-<repo-key>

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 plan to use L7 traffic policies, be sure to apply the CRDs for the Kubernetes Gateway API to your cluster, which are required to create waypoint proxies.
```
  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v/standard-install.yaml
  
```

Deploy the Istio ambient control plane

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}
profile: ambient
istio_cni:
  namespace: istio-system
  enabled: true
meshConfig:
  accessLogFile: /dev/stdout
  defaultConfig:
    proxyMetadata:
      ISTIO_META_DNS_AUTO_ALLOCATE: "true"
      ISTIO_META_DNS_CAPTURE: "true"
pilot:
  enabled: true
  env:
    PILOT_ENABLE_IP_AUTOALLOCATE: "true"
    PILOT_ENABLE_K8S_SELECT_WORKLOAD_ENTRIES: "false"
    PILOT_SKIP_VALIDATE_TRUST_DOMAIN: "true"
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}
profile: ambient
istio_cni:
  namespace: istio-system
  enabled: true
meshConfig:
  accessLogFile: /dev/stdout
  defaultConfig:
    proxyMetadata:
      ISTIO_META_DNS_AUTO_ALLOCATE: "true"
      ISTIO_META_DNS_CAPTURE: "true"
pilot:
  enabled: true
  env:
    PILOT_ENABLE_IP_AUTOALLOCATE: "true"
    PILOT_ENABLE_K8S_SELECT_WORKLOAD_ENTRIES: "false"
    PILOT_SKIP_VALIDATE_TRUST_DOMAIN: "true"
EOF

Install the Istio CNI node agent daemonset.

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

  helm upgrade --install istio-cni oci://${HELM_REPO}/cni \
--namespace kube-system \
--version ${ISTIO_IMAGE} \
-f - <<EOF
global:
  hub: ${REPO}
  platform: openshift
  tag: ${ISTIO_IMAGE}
profile: ambient
cni:
  ambient:
    dnsCapture: true
  excludeNamespaces:
  - istio-system
  - kube-system
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
kube-system    istio-cni-node-pr5rl                                1/1     Running   0               9s
kube-system    istio-cni-node-pvmx2                                1/1     Running   0               9s
kube-system    istio-cni-node-6q26l                                1/1     Running   0               9s

Deploy the Istio 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}
tag: ${ISTIO_IMAGE}
istioNamespace: istio-system
namespace: istio-system
profile: ambient
proxy:
  clusterDomain: cluster.local
terminationGracePeriodSeconds: 29
variant: distroless
EOF

  helm upgrade --install ztunnel oci://${HELM_REPO}/ztunnel \
--namespace istio-system \
--version ${ISTIO_IMAGE} \
-f - <<EOF
configValidation: true
enabled: true
env:
  L7_ENABLED: "true"
global:
  platform: openshift
hub: ${REPO}
tag: ${ISTIO_IMAGE}
istioNamespace: istio-system
namespace: istio-system
profile: ambient
proxy:
  clusterDomain: cluster.local
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
  
```

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

Create the gloo-mesh-gateways namespace. Note that you might choose a different namespace, such as istio-ingress or istio-gateways. If so, be sure to change the namespace in subsequent steps.
```
  kubectl create ns gloo-mesh-gateways
  
```

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: gloo-mesh-gateways
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

Deploy the Istio ingress gateway.

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

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 gloo-mesh-gateways

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

Deploy sample apps and add them to the ambient mesh.

Install Istio in ambient mode

Considerations link

Before you begin link

Install CRDs link

Deploy the Istio ambient control plane link

Deploy the Istio ambient data plane link

Next link

Considerations

Before you begin

Install CRDs

Deploy the Istio ambient control plane

Deploy the Istio ambient data plane

Next