Use Helm to link sidecar service meshes across multiple clusters.

Overview

In this guide, you deploy a sidecar mesh to each workload cluster, create an east-west gateway in each cluster, and link the istiod control planes across cluster networks by using peering gateways. In the next guide, you can deploy the Bookinfo sample app to the sidecar mesh in each cluster, and make select services available across the multicluster mesh. Incoming requests can then be routed from an ingress gateway, such as Gloo Gateway, to services in your mesh across all clusters.

The following diagram demonstrates a service mesh setup across multiple clusters.

Considerations

Before you install a multicluster sidecar mesh, review the following considerations and requirements.

License requirements

Version requirements

Review the following known Istio version requirements and restrictions.

• If you use Istio versions 1.27.7, 1.28.4, 1.29.0 or later, and you install the Solo Enterprise for Istio management plane into a namespace other than gloo-mesh, you must allow that namespace by listing it in the DEBUG_ENDPOINT_AUTH_ALLOWED_NAMESPACES environment variable of your istiod installation. For more information, see the release notes.
• 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 Solo Enterprise for Istio) on AWS Fargate. For more information, see the Amazon EKS issue.

Components

In the following steps, you install the Istio ambient components in each cluster to successfully create east-west gateways and establish multicluster peering, even if you plan to use a sidecar mesh. However, sidecar mesh setups continue to use sidecar injection for your workloads. Your workloads are not added to an ambient mesh. For more information about running both ambient and sidecar components in one mesh setup, see Ambient-sidecar interoperability.

Platform requirements

The steps in the following sections have options for deploying a multicluster 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.

Cross-cluster traffic addresses

In each cluster, you create an east-west gateway, which is implemented as a ztunnel that facilitates traffic between services across clusters in your multicluster mesh. In the Solo distribution of Istio 1.28 and later, you can use either LoadBalancer or NodePort addresses to resolve cross-cluster traffic requests through this gateway. Note that the NodePort method is considered alpha in the Solo distribution of Istio version 1.28.

LoadBalancer: In the standard LoadBalancer peering method, cross-cluster traffic through the east-west gateway resolves to its LoadBalancer address.

NodePort (alpha): If you prefer to use direct pod-to-pod traffic across clusters, you can annotate the east-west and peering gateways so that cross-cluster traffic resolves to NodePort addresses. This method allows you to avoid LoadBalancer services to reduce cross-cluster traffic costs. Review the following considerations:

• Note that the gateways must still be created with stable IP addresses, which are required for xDS communication with the istiod control plane in each cluster. NodePort peering is used for data-plane communication, in that requests to services resolve to the NodePort instead of the LoadBalancer address. Also, the east-west gateway must have the topology.istio.io/cluster label.
• If a node in a target cluster becomes inaccessible, such as during a restart or replacement, a delay can occur in the connection from the client cluster that must become aware of the new east-west gateway NodePort. In this case, you might see a connection error when trying to send cross-cluster traffic to an east-west gateway that is no longer accepting connections.
• Only nodes where an east-west gateway pod is provisioned are considered targets for traffic.
• NodePort peering uses only InternalIP node addresses. Ensure that your environment is configured so that nodes are reachable via their InternalIP address. If you need to use another address type, such as ExternalIP, contact Solo for engineering design and implementation support.
• Like LoadBalancer gateways, NodePort gateways support traffic from Envoy-based ingress gateways, waypoints, and sidecars.
• This feature is in an alpha state. Alpha features are likely to change, are not fully tested, and are not supported for production. For more information, see Solo feature maturity.
• This feature is only supported for default network setups, and is not applicable in flat network setups.

The steps in the following guide include options for either the LoadBalancer or NodePort method. A status condition on each east-west and remote peer gateway indicates which dataplane service type is in use.

Migrating from multicluster community Istio

If you previously used the multicluster feature in community Istio, and want to now migrate to multicluster peering in the Solo distribution of Istio, the DISABLE_LEGACY_MULTICLUSTER environment variable is introduced in the Solo distribution of Istio version 1.28 to disable the community multicluster mechanisms. Multicluster in community Istio uses remote secrets that contain kubeconfigs to watch resources on remote clusters. This system is incompatible with the decentralized, push-based model for peering in the Solo distribution of Istio. This variable causes istiod to ignore remote secrets so that it does not attempt to set up Kubernetes clients to connect to them.

• For fresh multicluster mesh installations with the Solo distribution of Istio, use this environment variable in your istiod settings. This setting serves as a recommended safety measure to prevent any use of remote secrets.
• If you want to initiate a multicluster migration from community Istio, contact a Solo account representative. An account representative can help you set up two revisions of Istio that each select a different set of namespaces, and set the DISABLE_LEGACY_MULTICLUSTER variable on the revision that uses the Solo distribution of Istio for multicluster peering.

Set up tools

1. Save the following environment details and install the Solo distribution of the istioctl binary.

   1. Set your Enterprise level license for Solo Enterprise for Istio 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. Note that you might have previously saved this key in another variable, such as ${SOLO_LICENSE_KEY} or ${GLOO_MESH_LICENSE_KEY}.

      export SOLO_ISTIO_LICENSE_KEY=<enterprise_license_key>

   2. Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions.

   3. Save the Solo distribution of Istio version.

      export ISTIO_VERSION=1.28.5
         export ISTIO_IMAGE=${ISTIO_VERSION}-solo
         ```<ol start="4">
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 Istio images built by Solo.io support article.

   # 12-character hash at the end of the 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}

5. Get the Solo distribution of Istio binary and install istioctl, which you use for multicluster linking and gateway commands. This script automatically detects your OS and architecture, downloads the appropriate Solo distribution of Istio binary, and verifies the installation.

   bash <(curl -sSfL https://raw.githubusercontent.com/solo-io/doc-examples/main/istio/install-istioctl.sh)
      export PATH=${HOME}/.istioctl/bin:${PATH}

6. Save the names and kubeconfig contexts of each cluster. This guide uses two clusters as an example. To add more clusters to the multicluster setup, include them in the arrays.

   export cluster1=<cluster1_name>
      export context1=<cluster1_context>
      export cluster2=<cluster2_name>
      export context2=<cluster2_context>

3. Deploy Istio to each cluster and link clusters. These steps vary based on whether you want to manually link meshes across clusters or use Solo Enterprise for Istio to automatically link clusters. Note that automatic linking is a beta feature, and requires Istio to be installed in the same cluster that the Gloo management plane is deployed to.

Option 1: Manually link meshes

In each cluster, use Helm to create the service mesh components. Then, create an east-west gateway so that traffic requests can be routed cross-cluster, and link clusters to enable cross-cluster service discovery.

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.

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

mkdir -p certs
pushd certs
make -f ../tools/certs/Makefile.selfsigned.mk root-ca

function create_cacerts_secret() {
  context=${1:?context}
  cluster=${2:?cluster}
  make -f ../tools/certs/Makefile.selfsigned.mk ${cluster}-cacerts
  kubectl --context=${context} create ns istio-system || true
  kubectl --context=${context} create secret generic cacerts -n istio-system \
    --from-file=${cluster}/ca-cert.pem \
    --from-file=${cluster}/ca-key.pem \
    --from-file=${cluster}/root-cert.pem \
    --from-file=${cluster}/cert-chain.pem
}

create_cacerts_secret ${context1} ${cluster1}
create_cacerts_secret ${context2} ${cluster2}

cd ../..

Deploy mesh components

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 --context ${context1}
   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml --context ${context2}

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

   for context in ${context1} ${context2}; do
     helm upgrade --install istio-base oci://${HELM_REPO}/base \
     --namespace istio-system \
     --kube-context ${context} \
     --version ${ISTIO_IMAGE} \
     --create-namespace \
     -f - <<EOF
   profile: ambient
   revision: main
   global:
     istioNamespace: istio-system
   EOF
   done

   for context in ${context1} ${context2}; do
     helm upgrade --install istio-base oci://${HELM_REPO}/base \
     --namespace istio-system \
     --create-namespace \
     --kube-context ${context} \
     --version ${ISTIO_IMAGE} \
     -f - <<EOF
   profile: ambient
   revision: main
   global:
     istioNamespace: istio-system
     platform: openshift
   EOF
   done

   You can optionally verify that the CRDs are successfully installed by running the following command.

   kubectl get crds -l app.kubernetes.io/instance=istio-base --kube-context ${context1}
   kubectl get crds -l app.kubernetes.io/instance=istio-base --kube-context ${context2}

   Example output:

   NAME                                       CREATED AT
   authorizationpolicies.security.istio.io    2025-12-16T22:56:00Z
   destinationrules.networking.istio.io       2025-12-16T22:56:00Z
   envoyfilters.networking.istio.io           2025-12-16T22:56:00Z
   gateways.networking.istio.io               2025-12-16T22:56:00Z
   peerauthentications.security.istio.io      2025-12-16T22:56:00Z
   proxyconfigs.networking.istio.io           2025-12-16T22:56:00Z
   requestauthentications.security.istio.io   2025-12-16T22:56:00Z
   segments.admin.solo.io                     2025-12-16T22:56:00Z
   serviceentries.networking.istio.io         2025-12-16T22:56:00Z
   sidecars.networking.istio.io               2025-12-16T22:56:00Z
   telemetries.telemetry.istio.io             2025-12-16T22:56:00Z
   virtualservices.networking.istio.io        2025-12-16T22:56:00Z
   wasmplugins.extensions.istio.io            2025-12-16T22:56:00Z
   workloadentries.networking.istio.io        2025-12-16T22:56:00Z
   workloadgroups.networking.istio.io         2025-12-16T22:56:00Z

3. Create the istiod control plane in your cluster.

   function install_istiod() {
     context=${1:?context}
     cluster=${2:?cluster}
     helm upgrade --install istiod oci://${HELM_REPO}/istiod \
     --namespace istio-system \
     --kube-context ${context} \
     --version ${ISTIO_IMAGE} \
     -f - <<EOF
   global:
     hub: ${REPO}
     variant: distroless
     proxy:
       clusterDomain: cluster.local
     tag: ${ISTIO_IMAGE}
     multiCluster:
       clusterName: ${cluster}
     network: ${cluster}
   profile: ambient
   revision: main
   pilot:
     cni:
       enabled: true
   meshConfig:
     accessLogFile: /dev/stdout
     defaultConfig:
       proxyMetadata:
         ISTIO_META_DNS_AUTO_ALLOCATE: "true"
         ISTIO_META_DNS_CAPTURE: "true"
     trustDomain: ${cluster}
   pilot:
     affinity:
       podAntiAffinity:
         preferredDuringSchedulingIgnoredDuringExecution:
           - podAffinityTerm:
               labelSelector:
                 matchExpressions:
                 - key: istio.io/rev
                   operator: In
                   values:
                   - main
               topologyKey: topology.kubernetes.io/zone
             weight: 100
     enabled: true
     env:
       PILOT_ENABLE_IP_AUTOALLOCATE: "true"
       PILOT_ENABLE_K8S_SELECT_WORKLOAD_ENTRIES: "false"
       PILOT_SKIP_VALIDATE_TRUST_DOMAIN: "true"
       AUTO_RELOAD_PLUGIN_CERTS: "true"
       PILOT_ENABLE_WORKLOAD_ENTRY_AUTOREGISTRATION: "true"
       PILOT_ENABLE_WORKLOAD_ENTRY_HEALTHCHECKS: "true"<pre><code>   DISABLE_LEGACY_MULTICLUSTER: &quot;true&quot;
   </code></pre>
   
   platforms:
     peering:
       enabled: true
   revisionTags:
   - default
   license:
     value: ${SOLO_ISTIO_LICENSE_KEY}
     # Uncomment if you prefer to specify your license secret
     # instead of an inline value.
     # secretRef:
     #   name:
     #   namespace:
   EOF
   }
   
   install_istiod ${context1} ${cluster1}
   install_istiod ${context2} ${cluster2}

   function install_istiod() {
     context=${1:?context}
     cluster=${2:?cluster}
     helm upgrade --install istiod oci://${HELM_REPO}/istiod \
     --namespace istio-system \
     --kube-context ${context} \
     --version ${ISTIO_IMAGE} \
     -f - <<EOF
   global:
     hub: ${REPO}
     variant: distroless
     platform: openshift
     proxy:
       clusterDomain: cluster.local
     tag: ${ISTIO_IMAGE}
     multiCluster:
       clusterName: ${cluster}
     network: ${cluster}
   profile: ambient
   revision: main
   pilot:
     cni:
       namespace: kube-system
       enabled: true
   meshConfig:
     accessLogFile: /dev/stdout
     defaultConfig:
       proxyMetadata:
         ISTIO_META_DNS_AUTO_ALLOCATE: "true"
         ISTIO_META_DNS_CAPTURE: "true"
     trustDomain: ${cluster}
   pilot:
     affinity:
       podAntiAffinity:
         preferredDuringSchedulingIgnoredDuringExecution:
           - podAffinityTerm:
               labelSelector:
                 matchExpressions:
                 - key: istio.io/rev
                   operator: In
                   values:
                   - main
               topologyKey: topology.kubernetes.io/zone
             weight: 100
     enabled: true
     env:
       PILOT_ENABLE_IP_AUTOALLOCATE: "true"
       PILOT_ENABLE_K8S_SELECT_WORKLOAD_ENTRIES: "false"
       PILOT_SKIP_VALIDATE_TRUST_DOMAIN: "true"
       AUTO_RELOAD_PLUGIN_CERTS: "true"
       PILOT_ENABLE_WORKLOAD_ENTRY_AUTOREGISTRATION: "true"
       PILOT_ENABLE_WORKLOAD_ENTRY_HEALTHCHECKS: "true"<pre><code>   DISABLE_LEGACY_MULTICLUSTER: &quot;true&quot;
   </code></pre>
   
   platforms:
     peering:
       enabled: true
   revisionTags:
   - default
   license:
     value: ${SOLO_ISTIO_LICENSE_KEY}
     # Uncomment if you prefer to specify your license secret
     # instead of an inline value.
     # secretRef:
     #   name:
     #   namespace:
   EOF
   }
   
   install_istiod ${context1} ${cluster1}
   install_istiod ${context2} ${cluster2}

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

   for context in ${context1} ${context2}; do
     helm upgrade --install istio-cni oci://${HELM_REPO}/cni \
     --namespace istio-system \
     --kube-context=${context} \
     --version ${ISTIO_IMAGE} \
     -f - <<EOF
   global:
     hub: ${REPO}
     proxy: ${ISTIO_IMAGE}
     variant: distroless
   profile: ambient
   revision: main
   cni:
     ambient:
       dnsCapture: true
     excludeNamespaces:
     - istio-system
     - kube-system
   EOF
   done

   for context in ${context1} ${context2}; do
     helm upgrade --install istio-cni oci://${HELM_REPO}/cni \
     --namespace kube-system \
     --kube-context=${context} \
     --version ${ISTIO_IMAGE} \
     --create-namespace \
     -f - <<EOF
   global:
     hub: ${REPO}
     proxy: ${ISTIO_IMAGE}
     variant: distroless
     platform: openshift
   profile: ambient
   revision: main
   cni:
     ambient:
       dnsCapture: true
     excludeNamespaces:
     - istio-system
     - kube-system
   EOF
   done

5. Verify that the components of the Istio 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 ${context1} | grep istio
   kubectl get pods -A --context ${context2} | grep istio

   Example output:

   istio-system   istio-cni-node-g84js                   1/1     Running   0          8s
   istio-system   istio-cni-node-gwssc                   1/1     Running   0          8s
   istio-system   istiod-main-7c59ff7bd7-4mc25           1/1     Running   0          19s

6. Optional: Check the istiod logs to verify that the certificate you generated earlier is picked up by istiod.

   kubectl logs deploy/istiod -n istio-system --context ${context1} | grep x509
   kubectl logs deploy/istiod -n istio-system --context ${context2} | grep x509

   Example output:

   2025-12-16T22:59:06.783901Z     info    x509 cert - Issuer: "CN=Intermediate CA,O=Istio,L=cluster-1", Subject: "", SN: def320623729b8370172413749143836, NotBefore: "2025-12-16T22:57:06Z", NotAfter: "2035-12-14T22:59:06Z"
   2025-12-16T22:59:06.783937Z     info    x509 cert - Issuer: "CN=Root CA,O=Istio", Subject: "CN=Intermediate CA,O=Istio,L=cluster-1", SN: 452d45254328667ccf8434c64c79fe789612bb5a, NotBefore: "2025-12-16T22:54:30Z", NotAfter: "2035-12-14T22:54:30Z"
   2025-12-16T22:59:06.783966Z     info    x509 cert - Issuer: "CN=Root CA,O=Istio", Subject: "CN=Root CA,O=Istio", SN: 38dad68e56ab8c506ae07454801f65b134bd9580, NotBefore: "2025-12-16T22:54:30Z", NotAfter: "2035-12-14T22:54:30Z"

7. Install the ztunnel daemonset. Note that this component is required to successfully peer clusters together.

   function install_ztunnel() {
     context=${1:?context}
     cluster=${2:?cluster}
     helm upgrade --install ztunnel oci://${HELM_REPO}/ztunnel \
     --namespace istio-system \
     --kube-context=${context} \
     --version ${ISTIO_IMAGE} \
     -f - <<EOF
   configValidation: true
   enabled: true
   env:
     L7_ENABLED: "true"
     ISTIO_META_DNS_CAPTURE: "true"
     SKIP_VALIDATE_TRUST_DOMAIN: "true"
   hub: ${REPO}
   istioNamespace: istio-system
   multiCluster:
     clusterName: ${cluster}
   network: ${cluster}
   namespace: istio-system
   profile: ambient
   proxy:
     clusterDomain: cluster.local
   tag: ${ISTIO_IMAGE}
   variant: distroless
   revision: main
   EOF
   }
   
   install_ztunnel ${context1} ${cluster1}
   install_ztunnel ${context2} ${cluster2}

   function install_ztunnel() {
     context=${1:?context}
     cluster=${2:?cluster}
     helm upgrade --install ztunnel oci://${HELM_REPO}/ztunnel \
     --namespace kube-system \
     --kube-context=${context} \
     --version ${ISTIO_IMAGE} \
     -f - <<EOF
   configValidation: true
   enabled: true
   env:
     L7_ENABLED: "true"
     ISTIO_META_DNS_CAPTURE: "true"
     SKIP_VALIDATE_TRUST_DOMAIN: "true"
   hub: ${REPO}
   istioNamespace: istio-system
   multiCluster:
     clusterName: ${cluster}
   network: ${cluster}
   namespace: kube-system
   profile: ambient
   global:
     platform: openshift
   proxy:
     clusterDomain: cluster.local
   tag: ${ISTIO_IMAGE}
   terminationGracePeriodSeconds: 29
   variant: distroless
   revision: main
   EOF
   }
   
   install_ztunnel ${context1} ${cluster1}
   install_ztunnel ${context2} ${cluster2}

8. 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 ${context1} | grep ztunnel
   kubectl get pods -A --context ${context2} | 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

9. Label the istio-system namespace with the clusters’ network names, which you previously set to each cluster name in the global.network field of the istiod installations. The ambient control plane uses this label internally to group pods that exist in the same L3 network.

   kubectl label namespace istio-system --context ${context1} topology.istio.io/network=${cluster1}
   kubectl label namespace istio-system --context ${context2} topology.istio.io/network=${cluster2}

10. Create an east-west gateway in the istio-eastwest namespace. In each cluster, the east-west gateway is implemented as a ztunnel that facilitates traffic between services across clusters in your multicluster mesh.

    You can use either LoadBalancer or NodePort addresses for cross-cluster traffic.

    Create the east-west gateway in both clusters. Cross-cluster traffic though this gateway resolves to the LoadBalancer address. For customization options, see the gateway guide in the Istio docs.

    • Solo distribution of istioctl: For more information about this command, see the CLI reference.

      function create_ew_gateway_lb() {
        context=${1:?context}
        cluster=${2:?cluster}
        kubectl create namespace istio-eastwest --context ${context}
        istioctl multicluster expose --namespace istio-eastwest --context ${context} --generate > ew-gateway-${cluster}.yaml
        kubectl apply -f ew-gateway-${cluster}.yaml --context ${context}
      }
      create_ew_gateway_lb ${context1} ${cluster1}
      create_ew_gateway_lb ${context2} ${cluster2}

    Create the east-west gateway in both clusters. Note that the gateway must still be created with a stable internal IP address, which is required for xDS communication with the istiod control plane in each cluster. NodePort peering is used for data plane communication, in that requests to services resolve to the NodePort instead of the gateway’s stable IP address. For more information about NodePort peering considerations and requirements, see Cross-cluster traffic addresses.

    • Solo distribution of istioctl: For more information about this command, see the CLI reference.

      function create_ew_gateway_nodeport() {
        context=${1:?context}
        cluster=${2:?cluster}
        kubectl create namespace istio-eastwest --context ${context}
        istioctl multicluster expose --namespace istio-eastwest --context ${context} --generate > ew-gateway-${cluster}.yaml
        kubectl apply -f ew-gateway-${cluster}.yaml --context ${context}
        kubectl annotate gateway istio-eastwest -n istio-eastwest peering.solo.io/data-plane-service-type=NodePort --context ${context}
      }
      
      create_ew_gateway_nodeport ${context1} ${cluster1}
      create_ew_gateway_nodeport ${context2} ${cluster2}

11. Verify that the east-west gateway is successfully deployed.

    kubectl get pods -n istio-eastwest --context ${context1}
    kubectl get pods -n istio-eastwest --context ${context2}

Link clusters

Link clusters to enable cross-cluster service discovery and allow traffic to be routed through east-west gateways across clusters.

1. Optional: Before you link clusters, you can check the individual readiness of each cluster for linking by running the istioctl multicluster check --precheck command. For more information about this command, see the CLI reference. If any checks fail, run the command with --verbose, and see Validate your multicluster setup.

istioctl multicluster check --precheck --contexts="$context1,$context2"

Before continuing to the next step, make sure that the following checks pass as expected:
✅ Relevant environment variables on istiod are supported.
✅ The license in use by istiod supports multicluster.
✅ All istiod, ztunnel, and east-west gateway pods are healthy.
✅ The east-west gateway is programmed.

istioctl multicluster link --namespace istio-eastwest --contexts="$context1,$context2" --preferred-data-plane-service-type nodeport

 Example output for two clusters:
 ```
 Gateway istio-eastwest/istio-remote-peer-cluster1 applied to cluster "cluster2" pointing to cluster "cluster1" (network "cluster1")
 Gateway istio-eastwest/istio-remote-peer-cluster2 applied to cluster "cluster1" pointing to cluster "cluster2" (network "cluster2")
 ```

istioctl multicluster link --namespace istio-eastwest --from ${context1} --to ${context2} --preferred-data-plane-service-type nodeport

 Example output:
 ```
 Gateway istio-eastwest/istio-remote-peer-cluster2 applied to cluster "cluster1" pointing to cluster "cluster2" (network "cluster2")
 ```

kubectl apply --context ${context1} -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    gateway.istio.io/service-account: istio-eastwest
    gateway.istio.io/trust-domain: ${cluster2}<pre><code>   # Uncomment for NodePort-based cross-cluster traffic
# peering.solo.io/preferred-data-plane-service-type: NodePort
</code></pre>

  labels:
    topology.istio.io/network: ${cluster2}<pre><code>   topology.kubernetes.io/region: &quot;&lt;cluster2_region&gt;&quot;
# Uncomment as needed
# topology.kubernetes.io/zone: &quot;&lt;cluster2_zone&gt;&quot;
</code></pre>

  name: istio-remote-peer-${cluster2}
  namespace: istio-eastwest
spec:
  addresses:
  # Change to 'type: Hostname' as needed, such as for AWS hostnames
  - type: IPAddress
    value: $CLUSTER2_EW_ADDRESS
  gatewayClassName: istio-remote
  listeners:<pre><code> # Comment HBONE out for NodePort-based cross-cluster traffic
</code></pre>

  - name: cross-network
    port: 15008
    protocol: HBONE
    tls:
      mode: Passthrough
  - name: xds-tls
    port: 15012
    protocol: TLS
    tls:
      mode: Passthrough
EOF
kubectl apply --context ${context2} -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    gateway.istio.io/service-account: istio-eastwest
    gateway.istio.io/trust-domain: ${cluster1}<pre><code>   # Uncomment for NodePort-based cross-cluster traffic
# peering.solo.io/preferred-data-plane-service-type: NodePort
</code></pre>

  labels:
    topology.istio.io/network: ${cluster1}<pre><code>   topology.kubernetes.io/region: &quot;&lt;cluster1_region&gt;&quot;
# Uncomment as needed
# topology.kubernetes.io/zone: &quot;&lt;cluster1_zone&gt;&quot;
</code></pre>

  name: istio-remote-peer-${cluster1}
  namespace: istio-eastwest
spec:
  addresses:
  # Change to 'type: Hostname' as needed, such as for AWS hostnames
  - type: IPAddress
    value: $CLUSTER1_EW_ADDRESS
  gatewayClassName: istio-remote
  listeners:<pre><code> # Comment HBONE out for NodePort-based cross-cluster traffic
</code></pre>

  - name: cross-network
    port: 15008
    protocol: HBONE
    tls:
      mode: Passthrough
  - name: xds-tls
    port: 15012
    protocol: TLS
    tls:
      mode: Passthrough
EOF

kubectl apply --context ${context1} -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    gateway.istio.io/service-account: istio-eastwest
    gateway.istio.io/trust-domain: ${cluster2}<pre><code>   # Uncomment for NodePort-based cross-cluster traffic
# peering.solo.io/preferred-data-plane-service-type: NodePort
</code></pre>

  labels:
    topology.istio.io/network: ${cluster2}<pre><code>   topology.kubernetes.io/region: &quot;&lt;cluster2_region&gt;&quot;
# Uncomment as needed
# topology.kubernetes.io/zone: &quot;&lt;cluster2_zone&gt;&quot;
</code></pre>

  name: istio-remote-peer-${cluster2}
  namespace: istio-eastwest
spec:
  addresses:
  # Change to 'type: Hostname' as needed, such as for AWS hostnames
  - type: IPAddress
    value: $CLUSTER2_EW_ADDRESS
  gatewayClassName: istio-remote
  listeners:<pre><code> # Comment HBONE out for NodePort-based cross-cluster traffic
</code></pre>

  - name: cross-network
    port: 15008
    protocol: HBONE
    tls:
      mode: Passthrough
  - name: xds-tls
    port: 15012
    protocol: TLS
    tls:
      mode: Passthrough
EOF

3. Verify that peer linking was successful by running the istioctl multicluster check command. If any checks fail, run the command with --verbose, and see Validate your multicluster setup.

istioctl multicluster check --contexts="$context1,$context2"

In this example output, the remote peer gateways are successfully connected, and all other checks passed successfully. No global services exist because no app services are exposed across clusters in the multicluster mesh yet.

=== Cluster: cluster1 ===
✅ Incompatible Environment Variable Check: all relevant environment variables are valid
✅ License Check: license is valid for multicluster
✅ CNI DNS Capture Check: AMBIENT_DNS_CAPTURE is enabled
✅ Pod Check (istiod): all pods healthy
✅ Pod Check (ztunnel): all pods healthy
✅ Pod Check (eastwest gateway istio-eastwest/istio-eastwest): all pods healthy
✅ Gateway Check: all eastwest gateways programmed
     ✅ istio-eastwest/istio-eastwest available at aab8471c7fcfa4a3c82f2d217b015d97-396238517.us-east-1.elb.amazonaws.com
✅ Peers Check: all clusters connected
     ✅ Connected to gloo-gateway-docs-mgt via ab46aa29a49914da789a6d5422aca279-541415195.us-east-2.elb.amazonaws.com
ℹ️  Shared Services Check: no globally shared services found
====== 
=== Cluster: cluster2 ===
✅ Incompatible Environment Variable Check: all relevant environment variables are valid
✅ License Check: license is valid for multicluster
✅ CNI DNS Capture Check: AMBIENT_DNS_CAPTURE is enabled
✅ Pod Check (istiod): all pods healthy
✅ Pod Check (ztunnel): all pods healthy
✅ Pod Check (eastwest gateway istio-eastwest/istio-eastwest): all pods healthy
✅ Gateway Check: all eastwest gateways programmed
✅ istio-eastwest/istio-eastwest available at ab46aa29a49914da789a6d5422aca279-541415195.us-east-2.elb.amazonaws.com
✅ Peers Check: all clusters connected
✅ Connected to gloo-mesh-core-docs-mgt via aab8471c7fcfa4a3c82f2d217b015d97-396238517.us-east-1.elb.amazonaws.com
ℹ️  Shared Services Check: no globally shared services found
✅ Intermediate Certs Compatibility Check: all clusters have compatible intermediate certificates
✅ Network Configuration Check: all network configurations are valid
✅ Stale Workloads Check: skipped (flat network not detected)

<div class="hextra-copy-icon hx:group-[.copied]/copybtn:hidden hx:pointer-events-none hx:h-4 hx:w-4"></div>

Example output for cluster1, in which you can verify that the istiod control plane for cluster2 is listed:

NAME                                               CLUSTER          ISTIOD                      VERSION              SUBSCRIBED TYPES
istio-eastwest-67fd5679dc-fhsxs.istio-eastwest     cluster1         istiod-7b7c9cc4c6-bdm9c     1.28.5-solo-fips     2 (WADS,WDS)
istiod-6bc6765484-5bbhd.istio-system               cluster2         istiod-7b7c9cc4c6-bdm9c     1.28.5-solo-fips     3 (FSDS,SGDS,WDS)
ztunnel-5f8rb.kube-system                          cluster1         istiod-7b7c9cc4c6-bdm9c     1.28.5-solo-fips     2 (WADS,WDS)
ztunnel-f96kh.kube-system                          cluster1         istiod-7b7c9cc4c6-bdm9c     1.28.5-solo-fips     2 (WADS,WDS)
ztunnel-vtj4f.kube-system                          cluster1         istiod-7b7c9cc4c6-bdm9c     1.28.5-solo-fips     2 (WADS,WDS)

Next: Add apps to the sidecar mesh. For multicluster setups, this includes making specific services available across your linked cluster setup.

Option 2: Automatically link clusters (beta)

In each cluster, use Helm to create the service mesh components, and create an east-west gateway so that traffic requests can be routed cross-cluster. Then, use the Gloo management plane to automate multicluster linking, which enables cross-cluster service discovery.

Enable automatic peering of clusters

Upgrade Solo Enterprise for Istio in your multicluster setup to enable the ConfigDistribution feature flag and install the enterprise CRDs, which are required for Solo Enterprise for Istio to automate peering and distribute gateways between clusters.

1. In the cluster where you installed the management plane, upgrade your gloo-platform-crds Helm release to include the following settings.

   helm get values gloo-platform-crds -n gloo-mesh -o yaml --kube-context ${context1} > mgmt-crds.yaml
   helm upgrade gloo-platform-crds gloo-platform/gloo-platform-crds \
     --kube-context ${context1} \
     --namespace gloo-mesh \
     -f mgmt-crds.yaml \
     --set featureGates.ConfigDistribution=true \
     --set installEnterpriseCrds=true

2. In the cluster where you installed the management plane, upgrade your gloo-platform Helm release to include the following settings.

   helm get values gloo-platform -n gloo-mesh -o yaml --kube-context ${context1} > mgmt-plane.yaml
   helm upgrade gloo-platform gloo-platform/gloo-platform \
     --kube-context ${context1} \
     --namespace gloo-mesh \
     -f mgmt-plane.yaml \
     --set featureGates.ConfigDistribution=true

3. In each connected cluster, upgrade your gloo-platform-crds Helm release to include the following settings. Repeat this step for each workload cluster.

   helm get values gloo-platform-crds -n gloo-mesh -o yaml --kube-context ${context2} > crds.yaml
   helm upgrade gloo-platform-crds gloo-platform/gloo-platform-crds \
     --kube-context ${context2} \
     --namespace gloo-mesh \
     -f crds.yaml \
     --set installEnterpriseCrds=true

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.

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

mkdir -p certs
pushd certs
make -f ../tools/certs/Makefile.selfsigned.mk root-ca

function create_cacerts_secret() {
  context=${1:?context}
  cluster=${2:?cluster}
  make -f ../tools/certs/Makefile.selfsigned.mk ${cluster}-cacerts
  kubectl --context=${context} create ns istio-system || true
  kubectl --context=${context} create secret generic cacerts -n istio-system \
    --from-file=${cluster}/ca-cert.pem \
    --from-file=${cluster}/ca-key.pem \
    --from-file=${cluster}/root-cert.pem \
    --from-file=${cluster}/cert-chain.pem
}

create_cacerts_secret ${context1} ${cluster1}
create_cacerts_secret ${context2} ${cluster2}

cd ../..

Deploy mesh components

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 --context ${context1}
   kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml --context ${context2}

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

for context in ${context1} ${context2}; do
  helm upgrade --install istio-base oci://${HELM_REPO}/base \
  --namespace istio-system \
  --kube-context ${context} \
  --version ${ISTIO_IMAGE} \
  --create-namespace \
  -f - <<EOF
profile: ambient
revision: main
global:
  istioNamespace: istio-system
EOF
done

for context in ${context1} ${context2}; do
  helm upgrade --install istio-base oci://${HELM_REPO}/base \
  --namespace istio-system \
  --create-namespace \
  --kube-context ${context} \
  --version ${ISTIO_IMAGE} \
  -f - <<EOF
profile: ambient
revision: main
global:
  istioNamespace: istio-system
  platform: openshift
EOF
done