Install ambient service meshes with Helm
Use Helm to deploy an ambient service mesh to your Gloo Mesh Core cluster.
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 and license requirements
Multicluster ambient setups:
- In Gloo Mesh version 2.7 and later, multicluster ambient setups require the Solo distribution of Istio version 1.24.3 or later (
1.24.3-solo
), including the Solo distribution ofistioctl
. - A Gloo Mesh Enterprise license. If you do not have one, contact an account representative.
Single cluster setups:
- In Gloo Mesh Core 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 tofalse
. For more information, see this upstream Istio issue. Note that this issue is resolved in Istio 1.22.4.
Revision and canary upgrade limitations
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, and the upgrade guides in this documentation set show you how to perform in-place upgrades only.
Single cluster
Install Istio in ambient mode in one cluster.
Step 1: Prepare the cluster environment
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.24.2 # 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}
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
If you use Google Kubernetes Engine (GKE) clusters, create the following
ResourceQuota
in theistio-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
Step 2: Install CRDs
Install the
base
chart, which contains the CRDs and cluster roles required to set up Istio.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
Step 3: Deploy the ambient control plane
Create the
istiod
control plane in your cluster.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.
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.
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
Multicluster
Install ambient service meshes with Helm in a multicluster Gloo Mesh Core environment.
Multicluster ambient capabilities require a Gloo Mesh Enterprise license. If you do not have one, contact an account representative.
Step 1: Prepare the cluster environments
Set environment variables for the Solo distribution of Istio that you want to install. 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 # in the format 1.x.x, with no tags export ISTIO_VERSION=1.24.2 # 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 distrubution of Istio patch version and tag, # image repo, Helm repo, and binary repo export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY} export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY} export BINARY_REPO=https://console.cloud.google.com/storage/browser/istio-binaries-${REPO_KEY}/${ISTIO_IMAGE}
Download the Solo distribution of Istio binary and install
istioctl
, which you use for multicluster linking and gateway commands.- Navigate to the storage repository for the Solo distribution of Istio binaries.
open ${BINARY_REPO}
- Download the
tar.gz
file for your system, such asistio-1.24.2-solo-osx-amd64.tar.gz
. - Extract the downloaded
tar.gz
file. - Navigate to the package directory and add the
istioctl
client to your system’sPATH
.cd istio-${ISTIO_IMAGE} export PATH=$PWD/bin:$PATH
- Verify that the
istioctl
client runs the Solo distribution of Istio that you want to install.Example output:istioctl version --remote=false
client version: 1.24.2-solo
- Navigate to the storage repository for the Solo distribution of Istio binaries.
- If you use Google Kubernetes Engine (GKE) clusters, create the following
ResourceQuota
in theistio-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 2: Create a shared root of trust
Each cluster in the multicluster setup must have a shared root of trust. This can be achieved by providing a root certificate signed by a PKI provider, or a custom root certificate created for this purpose. The root certificate signs a unique intermediate CA certificate for each cluster.
Step 3: Install CRDs
Save the name and kubeconfig context of a cluster where you want to install Istio 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=<cluster-name> export CLUSTER_CONTEXT=<cluster-context>
Install the
base
chart, which contains the CRDs and cluster roles required to set up Istio.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 --context ${CLUSTER_CONTEXT}
Step 4: Deploy the ambient control plane
Create the
istiod
control plane in your cluster.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.
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 --context ${CLUSTER_CONTEXT} | 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 5: Deploy the ambient data plane
Install the ztunnel daemonset.
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 --context ${CLUSTER_CONTEXT} | 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
Label the
istio-system
namespace with the cluster’s network name, which you previously set to your cluster’s name in theglobal.network
field of theistiod
installation. The ambient control plane uses this label internally to group pods that exist in the same L3 network.kubectl label namespace istio-system --context ${CLUSTER_CONTEXT} topology.istio.io/network=${CLUSTER_NAME}
Create an east-west gateway in the
istio-eastwest
namespace. An east-west gateway facilitates traffic between services in each cluster in your multicluster ambient mesh.- You can use the following
istioctl
command to quickly create the east-west gateway.kubectl create namespace istio-eastwest --context ${CLUSTER_CONTEXT} istioctl multicluster expose --namespace istio-eastwest --context ${CLUSTER_CONTEXT}
- To take a look at the Gateway resource that this command creates, you can include the
--generate
flag in the command.In this example output, thekubectl create namespace istio-eastwest --context ${CLUSTER_CONTEXT} istioctl multicluster expose --namespace istio-eastwest --context ${CLUSTER_CONTEXT} --generate
gatewayClassName
that is used,istio-eastwest
, is included by default in the ambient control plane installation.apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: labels: istio.io/expose-istiod: "15012" topology.istio.io/network: "<cluster_network_name>" name: istio-eastwest namespace: istio-eastwest spec: gatewayClassName: istio-eastwest listeners: - name: cross-network port: 15008 protocol: HBONE tls: mode: Passthrough - name: xds-tls port: 15012 protocol: TLS tls: mode: Passthrough
- You can use the following
Step 6: Repeat steps 3 - 5 for each cluster
For each cluster that you want to include in the multicluster ambient mesh setup, repeat steps 3 - 5 to install the CRDs, control plane, and data plane in each cluster. Remember to change the cluster name and context variables each time you repeat the steps.
export CLUSTER_NAME=<cluster-name>
export CLUSTER_CONTEXT=<cluster-context>
Step 7: Link clusters
Linking clusters enables cross-cluster service discovery and allows traffic to be routed through east-west gateways across clusters.
Verify that the contexts for the clusters that you want to include in the multicluster ambient mesh are listed in your kubeconfig file.
kubectl config get-contexts
- In the output, note the names of the cluster contexts, which you use in the next step to link the clusters.
- If you have multiple kubeconfig files, you can generate a merged kubeconfig file by running the following command.
KUBECONFIG=<kubeconfig_file1>.yaml:<file2>.yaml:<file3>.yaml kubectl config view --flatten
Using the names of the cluster contexts, link the clusters so that they can communicate. Note that you can either link the clusters bi-directionally or asymmetrically. In a standard bi-directional setup, services in any of the linked clusters can send requests to and receive requests from the services in any of the other linked clusters. In an asymmetrical setup, you allow one cluster to send requests to another cluster, but the other cluster cannot send requests back to the first cluster.
Note that these istio-remote
gateways are used for cluster peering only, and do not create deployments or services. Traffic requests between linked clusters are routed through the istio-eastwest
gateways.
For example, you can list the gateways in a cluster to see both the remote and east-west gateways.
kubectl get gateways -n istio-eastwest --context $CLUSTER_CONTEXT
NAME CLASS ADDRESS PROGRAMMED AGE
istio-eastwest istio-eastwest <address> True 29m
istio-remote-peer-cluster1 istio-remote <address> True 16m
However, if you list the services in the same namespace, only a service for the east-west gateway exists.
kubectl get svc -n istio-eastwest --context $CLUSTER_CONTEXT
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istio-eastwest LoadBalancer 172.20.44.255 <address> 15021:31730/TCP,15008:30632/TCP,15012:32356/TCP 29m
Next
Add apps to the ambient mesh. For multicluster setups, this includes making specific services available across your linked cluster setup.