Gloo Operator

Use the Gloo Operator to link 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

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.

Version requirements

Review the following known Istio version requirements and restrictions.

• To use the Solo distribution of Istio 1.30 for multicluster setups in which waypoint proxies are deployed, use patch version 1.30.2 or later. Patch versions 1.30.0 and 1.30.1 contain a bug in which the peering controller does not create a remote `ServiceEntry` for services whose pod selector matches waypoint proxy pods.
• In the Solo distribution of Istio 1.30 and 1.31, WorkloadEntry resources created by autoregistration might not carry the networking.istio.io/tunnel: http label. When that label is absent, ambient-enrolled pods send connections to the VM as plaintext instead of over HBONE. Because plaintext connections carry no mTLS client identity, any AuthorizationPolicy that uses source.principals to control inbound access to the VM always returns 403. As a workaround, manually label the gateway WorkloadEntry with networking.istio.io/tunnel: http to force HBONE, or replace source.principals conditions with source.ipBlocks until a patch release is available.

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 beta in the Solo distribution of Istio version 1.29.

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

NodePort (beta): 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. Before you use this feature, be sure to review its limitations, considerations, and best practices.

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. 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.30.3
   export ISTIO_IMAGE=${ISTIO_VERSION}-solo

4. Save the image and Helm repository information for the Solo distribution of Istio.

   • Istio 1.29 and later:

     export REPO=us-docker.pkg.dev/soloio-img/istio
     export HELM_REPO=us-docker.pkg.dev/soloio-img/istio-helm

   • Istio 1.28 and earlier: You must provide a 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>

Link meshes

In each cluster, use the Gloo Operator 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. Install the Gloo Operator to the gloo-mesh namespace. This operator deploys and manages your Istio installation. For more information, see the Helm reference.

   for context in ${context1} ${context2}; do
     helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
       --version 0.5.2 \
       -n gloo-mesh \
       --create-namespace \
       --kube-context ${context} \
       --set manager.env.SOLO_ISTIO_LICENSE_KEY=${SOLO_ISTIO_LICENSE_KEY}
   done

2. Verify that the operator pod is running.

   kubectl get pods -n gloo-mesh --context ${context1} -l app.kubernetes.io/name=gloo-operator
   kubectl get pods -n gloo-mesh --context ${context2} -l app.kubernetes.io/name=gloo-operator

   Example output:

   gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s
3. Create a ServiceMeshController custom resource to configure an Istio installation. For a description of each configurable field, see the ServiceMeshController reference. If you need to set more advanced Istio configuration, you can also create a gloo-extensions-config configmap.

   function create_smc() {
     context=${1:?context}
     cluster=${2:?cluster}
     kubectl apply -n gloo-mesh --context ${context} -f -<<EOF
   apiVersion: operator.gloo.solo.io/v1
   kind: ServiceMeshController
   metadata:
     name: managed-istio
     labels:
       app.kubernetes.io/name: managed-istio
   spec:
     cluster: ${cluster}
     network: ${cluster}
     dataplaneMode: Ambient # required for multicluster setups
     installNamespace: istio-system
     version: ${ISTIO_VERSION}
   EOF
   }
   
   create_smc ${context1} ${cluster1}
   create_smc ${context2} ${cluster2}
   info

   Note that the operator detects your cloud provider and cluster platform, and configures the necessary settings required for that platform for you. For example, if you create an ambient mesh in an OpenShift cluster, no OpenShift-specific settings are required in the ServiceMeshController, because the operator automatically sets the appropriate settings for OpenShift and your specific cloud provider accordingly.
   
   If you set the installNamespace to a namespace other than gloo-system, gloo-mesh, or istio-system, you must include the ‐‐set manager.env.WATCH_NAMESPACES=<namespace> setting.

4. Verify that the ServiceMeshController is ready. In the Status section of the output, make sure that all statuses are True, and that the phase is SUCCEEDED.

   kubectl describe servicemeshcontroller -n gloo-mesh managed-istio --context ${context1}
   kubectl describe servicemeshcontroller -n gloo-mesh managed-istio --context ${context2}

   Example output:

   ...
   Status:
     Conditions:
       Last Transition Time:  2024-12-27T20:47:01Z
       Message:               Manifests initialized
       Observed Generation:   1
       Reason:                ManifestsInitialized
       Status:                True
       Type:                  Initialized
       Last Transition Time:  2024-12-27T20:47:02Z
       Message:               CRDs installed
       Observed Generation:   1
       Reason:                CRDInstalled
       Status:                True
       Type:                  CRDInstalled
       Last Transition Time:  2024-12-27T20:47:02Z
       Message:               Deployment succeeded
       Observed Generation:   1
       Reason:                DeploymentSucceeded
       Status:                True
       Type:                  ControlPlaneDeployed
       Last Transition Time:  2024-12-27T20:47:02Z
       Message:               Deployment succeeded
       Observed Generation:   1
       Reason:                DeploymentSucceeded
       Status:                True
       Type:                  CNIDeployed
       Last Transition Time:  2024-12-27T20:47:02Z
       Message:               Deployment succeeded
       Observed Generation:   1
       Reason:                DeploymentSucceeded
       Status:                True
       Type:                  WebhookDeployed
       Last Transition Time:  2024-12-27T20:47:02Z
       Message:               All conditions are met
       Observed Generation:   1
       Reason:                SystemReady
       Status:                True
       Type:                  Ready
     Phase:                   SUCCEEDED
   Events:                    <none>

5. Verify that the istiod control plane, Istio CNI, and ztunnel pods are running.

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

   Example output:

   NAME                          READY   STATUS    RESTARTS   AGE
   istio-cni-node-6s5nk          1/1     Running   0          2m53s
   istio-cni-node-blpz4          1/1     Running   0          2m53s
   istiod-gloo-bb86b959f-msrg7   1/1     Running   0          2m45s
   istiod-gloo-bb86b959f-w29cm   1/1     Running   0          3m
   ztunnel-mx8nw                 1/1     Running   0          2m52s
   ztunnel-w8r6c                 1/1     Running   0          2m52s

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

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

   • Helm: For more information about the peering chart, see the Helm values reference. For recommendations on customizing the east-west gateway for resiliency and availability with the Helm chart, see the best practices for multicluster peering.

     function create_ew_gateway_lb_helm() {
       context=${1:?context}
       cluster=${2:?cluster}
       helm upgrade -i peering-eastwest oci://${HELM_REPO}/peering \
         --version ${ISTIO_IMAGE} \
         --namespace istio-eastwest \
         --kube-context ${context} \
         -f - <<EOF
     eastwest:
       create: true
       cluster: ${cluster}
       # The network that the istio-system namespace is labeled with.
       # In prod environments, network and cluster are likely not the same value.
       network: ${cluster}
       deployment: {}
     EOF
     }
     create_ew_gateway_lb_helm ${context1} ${cluster1}
     create_ew_gateway_lb_helm ${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}

   • Helm: For more information about the peering chart, see the Helm values reference. For recommendations on customizing the east-west gateway for resiliency and availability with the Helm chart, see the best practices for multicluster peering.

     function create_ew_gateway_nodeport_helm() {
       context=${1:?context}
       cluster=${2:?cluster}
       helm upgrade -i peering-eastwest oci://${HELM_REPO}/peering \
         --version ${ISTIO_IMAGE} \
         --namespace istio-eastwest \
         --kube-context ${context} \
         -f - <<EOF
     eastwest:
       create: true
       cluster: ${cluster}
       # The network that the istio-system namespace is labeled with.
       # In prod environments, network and cluster are likely not the same value.
       network: ${cluster}
       dataplaneServiceTypes: nodeport
       deployment: {}
     EOF
     }
     
     create_ew_gateway_nodeport_helm ${context1} ${cluster1}
     create_ew_gateway_nodeport_helm ${context2} ${cluster2}

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

2. Link clusters to enable cross-cluster service discovery and allow traffic to be routed through east-west gateways across clusters. 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.

   In the Solo distribution of Istio 1.29 or later, you can use the peering Helm chart to link your clusters.For more information about the peering chart, see the Helm values reference.

   1. Get the addresses of the east-west gateway in each cluster. The following commands show examples for two clusters.

      export CLUSTER1_EW_ADDRESS=$(kubectl get svc -n istio-eastwest istio-eastwest --context ${context1} -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
      export CLUSTER2_EW_ADDRESS=$(kubectl get svc -n istio-eastwest istio-eastwest --context ${context2} -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
      echo "Cluster1 east-west gateway: $CLUSTER1_EW_ADDRESS"
      echo "Cluster2 east-west gateway: $CLUSTER2_EW_ADDRESS"

   2. Link the clusters by creating Helm releases in each cluster to represent the other clusters. In each cluster where you create Helm releases, a Gateway resource is created that uses the istio-remote GatewayClass. This class allows the gateway to connect to other clusters by using the addresses of the east-west gateways.

      • Be sure to update the region, and optionally zone, of each cluster.
      • If you want to use NodePorts instead of the gateway LoadBalancer IP address for cross-cluster traffic, change the preferredDataplaneServiceType to nodeport. This automatically configures the peering gateways for NodePort-based cross-cluster traffic.For more information about NodePort peering considerations and requirements, see Cross-cluster traffic addresses.
      • The following example depicts a bi-directional setup. In an asymmetrical setup, you create Helm releases to only represent the directionality you want to allow.

      helm upgrade -i peering-remote oci://${HELM_REPO}/peering \
        --version ${ISTIO_IMAGE} \
        --namespace istio-eastwest \
        --kube-context ${context1} \
        -f - <<EOF
      remote:
        create: true
        items:
          # Remote peer configuration for cluster2
          - name: istio-remote-peer-${cluster2}
            cluster: ${cluster2}
            network: ${cluster2}
            # Change to "Hostname" if using hostname
            addressType: IPAddress
            address: ${CLUSTER2_EW_ADDRESS}
            # Change to "nodeport" if using NodePorts
            preferredDataplaneServiceType: loadbalancer
            trustDomain: cluster.local
            region: "<cluster2_region>"
            # Uncomment as needed
            # zone: "<cluster2_zone>"
      EOF
      helm upgrade -i peering-remote oci://${HELM_REPO}/peering \
        --version ${ISTIO_IMAGE} \
        --namespace istio-eastwest \
        --kube-context ${context2} \
        -f - <<EOF
      remote:
        create: true
        items:
          # Remote peer configuration for cluster1
          - name: istio-remote-peer-${cluster1}
            cluster: ${cluster1}
            network: ${cluster1}
            # Change to "Hostname" if using hostname
            addressType: IPAddress
            address: ${CLUSTER1_EW_ADDRESS}
            # Change to "nodeport" if using NodePorts
            preferredDataplaneServiceType: loadbalancer
            trustDomain: cluster.local
            region: "<cluster1_region>"
            # Uncomment as needed
            # zone: "<cluster1_zone>"
      EOF

   Use the istioctl multicluster link command to quickly link clusters.

   1. Verify that the contexts for the clusters that you want to include in the multicluster mesh are listed in your kubeconfig file, which is required for the istioctl multicluster link command. If you do not have access to the kubeconfig files, use the Helm or declarative resources tabs.

      kubectl config get-contexts
      • If you have multiple kubeconfig files, you can generate a merged kubeconfig file by running the following command.

        KUBECONFIG=<kubeconfig_file1>.yaml:<file2>.yaml kubectl config view --flatten

   2. Using the names of the cluster contexts, link the clusters so that they can communicate. To take a look at the Gateway resources that this command creates, you can include the --generate flag in the command. For more information about this command, see the CLI reference.

      • Bi-directional: You can use the following istioctl command to quickly link the clusters bi-directionally. In each cluster, Gateway resources are created that use the istio-remote GatewayClass. This class allows the gateways to connect to other clusters by using the addresses of the east-west gateways.

        istioctl multicluster link --namespace istio-eastwest --contexts="$context1,$context2"

        If you want to use NodePorts instead of the gateway LoadBalancer IP address for cross-cluster traffic, use the –preferred-data-plane-service-type nodeport flag when linking clusters. This enablement automatically configures the peering gateways for NodePort-based cross-cluster traffic. For more information about NodePort peering considerations and requirements, see Cross-cluster traffic addresses.

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

      • Asymmetrical: You can use the following istioctl command to quickly link the clusters asymmetrically. The services in the cluster in the --from flag can send requests to services in the cluster in the --to flag, but sending requests in the reverse direction is not permitted.

        For example, this command allows services in cluster1’s mesh to send requests to services in cluster2’s mesh through cluster2’s east-west gateway. However, the reverse is not permitted: services in cluster2’s mesh cannot send requests through cluster1’s east-west gateway to services in cluster1.

        istioctl multicluster link --namespace istio-eastwest --from ${context1} --to ${context2}

        If you want to use NodePorts instead of the gateway LoadBalancer IP address for cross-cluster traffic, use the –preferred-data-plane-service-type nodeport flag when linking clusters. This automatically configures the peering gateways for NodePort-based cross-cluster traffic. For more information about NodePort peering considerations and requirements, see Cross-cluster traffic addresses.

        Example output:

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

   Link the clusters by declaratively creating istio-remote peer gateways.

   Bi-directional: Use the following Gateway resources to create an istio-remote peer gateway in each cluster. The istio-remote GatewayClass allows the gateways to connect to other clusters by using the addresses of the east-west gateways.

   1. Get the addresses of the east-west gateway in each cluster. The following commands show examples for two clusters.

      export CLUSTER1_EW_ADDRESS=$(kubectl get svc -n istio-eastwest istio-eastwest --context ${context1} -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
      export CLUSTER2_EW_ADDRESS=$(kubectl get svc -n istio-eastwest istio-eastwest --context ${context2} -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
      
      echo "Cluster1 east-west gateway: $CLUSTER1_EW_ADDRESS"
      echo "Cluster2 east-west gateway: $CLUSTER2_EW_ADDRESS"

   2. Using the east-west gateway addresses, create a Gateway resource in each cluster to represent the other cluster.

      • In the labels section, be sure to update the locality labels according to the region, and optionally zone, of each cluster. For more information about locality support, see the release notes.
      • If you want to use NodePorts instead of the gateway LoadBalancer IP address for cross-cluster traffic, uncomment the peering.solo.io/preferred-data-plane-service-type: NodePort annotation from each Gateway resource. Additionally, you can comment out the HBONE listener in each gateway, because traffic is routed through the NodePort directly. For more information about NodePort peering considerations and requirements, see Cross-cluster traffic addresses.

      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}
          # Uncomment for NodePort-based cross-cluster traffic
          # peering.solo.io/preferred-data-plane-service-type: NodePort
        labels:
          topology.istio.io/network: ${cluster2}
          topology.kubernetes.io/region: "<cluster2_region>"
          # Uncomment as needed
          # topology.kubernetes.io/zone: "<cluster2_zone>"
        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:
        # Comment HBONE out for NodePort-based cross-cluster traffic
        - 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}
          # Uncomment for NodePort-based cross-cluster traffic
          # peering.solo.io/preferred-data-plane-service-type: NodePort
        labels:
          topology.istio.io/network: ${cluster1}
          topology.kubernetes.io/region: "<cluster1_region>"
          # Uncomment as needed
          # topology.kubernetes.io/zone: "<cluster1_zone>"
        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:
        # Comment HBONE out for NodePort-based cross-cluster traffic
        - name: cross-network
          port: 15008
          protocol: HBONE
          tls:
            mode: Passthrough
        - name: xds-tls
          port: 15012
          protocol: TLS
          tls:
            mode: Passthrough
      EOF

   Asymmetrical: Use the following Gateway resources to create an istio-remote peer gateway in only some clusters. The istio-remote GatewayClass allows the gateway in one cluster to connect to another cluster by using the address of the east-west gateway, but sending requests in the reverse direction is not permitted.

   1. Get the address of the east-west gateway in the cluster that you want to send traffic to. The following command shows an example for cluster2.

      export CLUSTER2_EW_ADDRESS=$(kubectl get svc -n istio-eastwest istio-eastwest --context ${context2} -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
      
      echo "Cluster2 east-west gateway: $CLUSTER2_EW_ADDRESS"

   2. Using the east-west gateway address, create a Gateway resource in the cluster that you want to send requests from. For example, this Gateway resource allows services in cluster1’s mesh to send requests to services in cluster2’s mesh through cluster2’s east-west gateway. However, the reverse is not permitted: services in cluster2’s mesh cannot send requests through cluster1’s east-west gateway to services in cluster1.

      • In the labels section, be sure to update the locality labels according to the region, and optionally zone, of each cluster. For more information about locality support, see the release notes.
      • If you want to use NodePorts instead of the gateway LoadBalancer IP address for cross-cluster traffic, uncomment the peering.solo.io/preferred-data-plane-service-type: NodePort annotation from each Gateway resource. Additionally, you can comment out the HBONE listener in each gateway, because traffic is routed through the NodePort directly. For more information about NodePort peering considerations and requirements, see Cross-cluster traffic addresses.

      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}
          # Uncomment for NodePort-based cross-cluster traffic
          # peering.solo.io/preferred-data-plane-service-type: NodePort
        labels:
          topology.istio.io/network: ${cluster2}
          topology.kubernetes.io/region: "<cluster2_region>"
          # Uncomment as needed
          # topology.kubernetes.io/zone: "<cluster2_zone>"
        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:
        # Comment HBONE out for NodePort-based cross-cluster traffic
        - 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: arn:aws:eks:us-east-1:111122223333: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 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-1111111111.us-east-1.elb.amazonaws.com
   ✅ Peers Check: all clusters connected
        ✅ Connected to cluster2 via bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb-2222222222.us-east-2.elb.amazonaws.com
   ✅ Remote Gateway Service Account Check: all remote gateway service accounts match
   ℹ️ Shared Services Check: no globally shared services found
   ✅ Service Check: no conflicting service aliases or hostnames found
   ✅ Peer Segments Check: no rejected peer segments found
   ✅ Missing Local Segment Check: all peer Segments have matching local Segment resources
   ✅ Hostname Conflict Check: no hostname conflicts detected in auto-generated ServiceEntry resources
   ====== 
   === Cluster: arn:aws:eks:us-east-2:111122223333: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 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb-2222222222.us-east-2.elb.amazonaws.com
   ✅ Peers Check: all clusters connected
        ✅ Connected to cluster1 via aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-1111111111.us-east-1.elb.amazonaws.com
   ✅ Remote Gateway Service Account Check: all remote gateway service accounts match
   ℹ️ Shared Services Check: no globally shared services found
   ✅ Service Check: no conflicting service aliases or hostnames found
   ✅ Peer Segments Check: no rejected peer segments found
   ✅ Missing Local Segment Check: all peer Segments have matching local Segment resources
   ✅ Hostname Conflict Check: no hostname conflicts detected in auto-generated ServiceEntry resources
   ====== 
   ✅ Intermediate Certs Compatibility Check: all clusters have compatible intermediate certificates
   ✅ Network Configuration Check: all network configurations are valid
   ✅ ISTIO_META_NETWORK Check: all ISTIO_META_NETWORK values match network label
   ✅ Stale Workloads Check: skipped (flat network not detected)

4. Optional: Verify that the istiod control plane for each peered cluster is included in each cluster’s proxy status list.

   istioctl proxy-status --context ${context1}
   istioctl proxy-status --context ${context2}

   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.30.3-solo-fips     2 (WADS,WDS)
   istiod-6bc6765484-5bbhd.istio-system               cluster2         istiod-7b7c9cc4c6-bdm9c     1.30.3-solo-fips     3 (FSDS,SGDS,WDS)
   ztunnel-5f8rb.kube-system                          cluster1         istiod-7b7c9cc4c6-bdm9c     1.30.3-solo-fips     2 (WADS,WDS)
   ztunnel-f96kh.kube-system                          cluster1         istiod-7b7c9cc4c6-bdm9c     1.30.3-solo-fips     2 (WADS,WDS)
   ztunnel-vtj4f.kube-system                          cluster1         istiod-7b7c9cc4c6-bdm9c     1.30.3-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.

Next

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

Optional: Validate your multicluster setup

istioctl multicluster check

You can use the istioctl multicluster check --precheck command to check the individual readiness of each cluster before running istioctl multicluster link to link them in a multicluster mesh, and run it again after linking to confirm that the connections were successful. This command performs checks listed in the following sections, which you can review to understand what each check validates. Additionally, if any of the checks fail, run the command with the --verbose option, and review the following troubleshooting recommendations.

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

For more information about this command, see the CLI reference.

Starting in version 1.30, you can pass -o json or -o yaml to emit all check results grouped by cluster as a structured document. You can also run the command against an extracted bug-report directory to perform offline multicluster analysis without direct cluster access.

Incompatible environment variables

Checks whether the ENABLE_PEERING_DISCOVERY=true and optionally K8S_SELECT_WORKLOAD_ENTRIES=true environment variables are set incorrectly or are not supported for multicluster ambient mesh.

Example verbose output:

--- Incompatible Environment Variable Check ---

✅ Incompatible Environment Variable Check: K8S_SELECT_WORKLOAD_ENTRIES is valid ("")
✅ Incompatible Environment Variable Check: ENABLE_PEERING_DISCOVERY is valid ("true")
✅ Incompatible Environment Variable Check: all relevant environment variables are valid

If this check fails, check your environment variables in your istiod configuration, such as by running helm get values --kube-context ${CLUSTER_CONTEXT} istiod -n istio-system -o yaml, and update your configuration.

License validity

Checks whether the license in use by istiod is valid for multicluster ambient mesh. Multicluster capabilities require an Enterprise level license for Solo Enterprise for Istio.

Example verbose output:

--- License Check ---

✅ License Check: license is valid for multicluster

If your license does not support multicluster ambient mesh, contact your Solo account representative.

CNI DNS capture

Checks whether ambient DNS capture is enabled in the istio-cni-config ConfigMap. DNS capture is required for workloads to resolve global hostnames (.mesh.internal and custom Segment domains) used to route traffic to services across clusters. The check returns a warning if AMBIENT_DNS_CAPTURE is not set or is not true.

Example verbose output:

--- CNI DNS Capture Check ---

✅ CNI DNS Capture Check: AMBIENT_DNS_CAPTURE is enabled

If this check fails or warns, verify the value in the ConfigMap:

kubectl get configmap istio-cni-config -n istio-system \
  -o jsonpath='{.data.AMBIENT_DNS_CAPTURE}'

To enable DNS capture, set values.cni.ambient.dnsCapture=true in the istiod Helm chart values and upgrade your installation.

Pod health

Checks the health of the pods in the cluster. All istiod, ztunnel, and east-west gateway pods across the checked clusters must be healthy and running for the multicluster mesh to function correctly.

Example verbose output:

--- Pod Check (istiod) ---

NAME                        READY     STATUS      RESTARTS     AGE
istiod-6d9cdf88cf-l47tf     1/1       Running     0            10m18s

✅ Pod Check (istiod): all pods healthy


--- Pod Check (ztunnel) ---

NAME              READY     STATUS      RESTARTS     AGE
ztunnel-dvlwk     1/1       Running     0            10m6s

✅ Pod Check (ztunnel): all pods healthy


--- Pod Check (eastwest gateway) ---

NAME                                READY     STATUS      RESTARTS     AGE
istio-eastwest-857b77fc5d-qgnrl     1/1       Running     0            9m33s

✅ Pod Check (eastwest gateway): all pods healthy

To check any unhealthy pods, run the following commands. Consider checking the pod logs, and review Debug Istio.

kubectl get po -n istio-system
kubectl get po -n istio-eastwest

East-west gateway status

Checks the status of the east-west gateways in the cluster. When an east-west gateway is created, the gateway controller creates a Kubernetes service to expose the gateway. Once this service is correctly attached to the gateway and has an address assigned, the east-west gateway has a Programmed status of true.

Example verbose output:

--- Gateway Check ---

Gateway: istio-eastwest
Addresses:
- 172.18.7.110
Status: programmed ✅

✅ Gateway Check: all eastwest gateways programmed

If the Programmed status is not true, an issue might exist with the address allocation for the service. Check the east-west gateway with a command such as kubectl get svc -n istio-eastwest, and verify that your cloud provider can correctly allocate addresses to the service.

NodePort east-west gateway health

For east-west gateways configured for NodePort peering, checks that the gateway has not fallen back to reporting a ClusterIP address, and validates that the backing Service has a port named hbone.

Example verbose output:

--- NodePort Gateway Health Check ---

Gateway: istio-eastwest
Backing service has hbone port ✅
NodePort address detected ✅

✅ NodePort Gateway Health Check: all NodePort east-west gateways valid

If this check fails, verify that the backing Service for the east-west gateway has a port named hbone and is correctly annotated for NodePort peering. You can also inspect the gloo.solo.io/NodePortConfigured status condition on the gateway: when True with reason Programmed, the HBONE port is correctly configured; when False with reason MissingHbonePort, the port is absent from the backing Service.

Remote peer gateway status

Checks the status of the remote peer gateways in the cluster, which represent the other peered clusters in the multicluster setup. These remote gateways configure the connection between the local cluster’s istiod control plane, and the peered clusters’ remote networks to enable xDS communication between peers. When the initial network connection between istiod and a remote peer is made, the gateway’s gloo.solo.io/PeerConnected status updates to true. Then, when the full xDS sync occurs between peers, the gateway’s gloo.solo.io/PeeringSucceeded status also updates to true. This check ensures that both statuses are true, and that the topology.istio.io/cluster label is set on the gateway.

Example verbose output:

--- Peers Check ---

Cluster: cluster2
Addresses:
- 172.18.7.130
Conditions:
- Accepted: True
- Programmed: True
- gloo.solo.io/PeerConnected: True
- gloo.solo.io/PeeringSucceeded: True
- gloo.solo.io/PeerDataPlaneProgrammed: True
Status: connected ✅

✅ Peers Check: all clusters connected

If the connection is severed between the peers, the gloo.solo.io/PeerConnected status becomes false. A failed connection between peers can be due to either a misconfiguration in the peering setup, or a network issue blocking port 15008 on the remote cluster, which is the cross-network HBONE port that the east-west gateway listens on. Review the steps you took to link clusters together, such as the steps outlined in the Helm default network guide. Additionally, review any firewall rules or network policies that might block access through port 15008 on the remote cluster.

Remote gateway service account

Checks that the effective service account for each istio-remote Gateway resource matches the corresponding peer east-west gateway in the remote cluster. A mismatch can cause authentication failures when the local istiod control plane attempts to connect to the remote cluster.

Example verbose output:

--- Remote Gateway Service Account Check ---

Remote gateway istio-eastwest/istio-remote-peer-cluster2 service account: istio-eastwest/istio-eastwest ✅

✅ Remote Gateway Service Account Check: all remote gateway service accounts match

If this check fails, review the service account configuration on your istio-remote Gateway resources and confirm they match the service account used by the east-west gateway in the corresponding remote cluster.

Intermediate certificate compatibility

Confirms the certificate compatibility between peered clusters. This check reads the root-cert.pem from the istio-ca-root-cert configmap in the istio-system namespace, and uses x509 certificate validation to confirm the root cert is compatible with all of the clusters’ ca-cert.pem intermediate certificate chains from the cacerts secret.

Example verbose output:

--- Intermediate Certs Compatibility Check ---

ℹ  Intermediate Certs Compatibility Check: cluster cluster1 root certificate SHA256 sum: 6d18f32e134824c158d97f32618657c45d5a83839f838ada751757139481537e
ℹ  Intermediate Certs Compatibility Check: cluster cluster2 root certificate SHA256 sum: 6d18f32e134824c158d97f32618657c45d5a83839f838ada751757139481537e
✅ Intermediate Certs Compatibility Check: cluster cluster1 has compatible intermediate certificates with cluster cluster2 
✅ Intermediate Certs Compatibility Check: cluster cluster2 has compatible intermediate certificates with cluster cluster1 
✅ Intermediate Certs Compatibility Check: all clusters have compatible intermediate certificates

If this check fails because the root certs are not valid for each peered clusters’ intermediate certificate chain, you can check the istiod logs for TLS errors when attempting to communicate with a peered cluster, such as the following:

2025-12-04T22:09:22.474517Z     warn    deltaadsc       disconnected, retrying in 24.735483751s: delta stream: rpc error: code = Unavailable desc = connection error: desc = "error reading server preface: remote error: tls: unknown certificate authority"       target=peering-cluster2

Ensure each cluster has a cacerts secret in the istio-system namespace. To regenerate invalid certificates for each cluster, follow the example steps in Create a shared root of trust.

Network configuration

Confirms the network configuration of the multicluster mesh. For multicluster peering setups that do not use a flat network topology, each cluster must occupy a unique network. The network name must be defined with the label topology.istio.io/network and set on both the istio-system namespace and the istio-eastwest gateway resource. The same network name must also be set as the NETWORK environment variable on the ztunnel daemonset. Each remote gateway that represents that cluster must have the topology.istio.io/network label equal to the network of the remote cluster.Each remote gateway must also have the topology.istio.io/cluster label set to the cluster ID of the remote cluster. This label is required for the peering controller to federate workload entries correctly. If a remote gateway is missing the topology.istio.io/cluster label, the check returns an error. If the label references a cluster ID not included in –contexts, the check returns an informational message.

Example verbose output:

--- Network Configuration Check ---

✅ Cluster cluster1 has network: cluster1
✅ Eastwest gateway istio-eastwest/istio-eastwest has correct network label: cluster1
✅ Cluster cluster2 has network: cluster2
✅ Eastwest gateway istio-eastwest/istio-eastwest has correct network label: cluster2
✅ Remote gateway istio-eastwest/istio-remote-peer-cluster2 references network cluster2 (clusters: [cluster2])
✅ Remote gateway istio-eastwest/istio-remote-peer-cluster1 references network cluster1 (clusters: [cluster1])
✅ Network Configuration Check: all network configurations are valid

Mismatched network identities cause errors in cross-cluster communication, which leads to error logs in ztunnel pods that indicate a network timeout on the outbound communication. Notably, the destination address on these errors is a 240.X.X.X address, instead of the correct remote peer gateway address. You can run kubectl logs -l app=ztunnel -n istio-system --tail=10 --context ${CLUSTER_CONTEXT} | grep -iE "error|warn" to review logs such as the following:

2025-11-18T16:14:53.490573Z     error   access  connection complete     src.addr=240.0.2.27:46802 src.workload="ratings-v1-5dc79b6bcd-zm8v6" src.namespace="bookinfo" src.identity="spiffe://cluster.local/ns/bookinfo/sa/bookinfo-ratings" dst.addr=240.0.9.43:15008 dst.hbone_addr=240.0.9.43:9080 dst.service="productpage.bookinfo.mesh.internal" dst.workload="autogenflat.portfolio1-soloiopoc-cluster1.bookinfo.productpage-v1-54bb874995-hblwp.ee508601917c" dst.namespace="bookinfo" dst.identity="spiffe://cluster.local/ns/bookinfo/sa/bookinfo-productpage" direction="outbound" bytes_sent=0 bytes_recv=0 duration="10001ms" error="connection timed out, maybe a NetworkPolicy is blocking HBONE port 15008: deadline has elapsed"

To troubleshoot these issues, be sure that you use unique network names to represent each cluster, and that you correctly labeled the cluster’s istio-system namespace with that network name, such as by running kubectl label namespace istio-system --context ${CLUSTER_CONTEXT} topology.istio.io/network=${CLUSTER_NAME}. You can also relabel the east-west gateway in the cluster, and the remote peer gateways in other clusters that represent this cluster.

ISTIO_META_NETWORK environment variable

Validates that all Istio proxy containers and sidecar-injector ConfigMap templates have ISTIO_META_NETWORK set, and that the value matches the topology.istio.io/network label on the istio-system namespace. A mismatch or missing value can cause network topology errors in multicluster routing.

Example verbose output:

--- ISTIO_META_NETWORK Check ---

✅ ISTIO_META_NETWORK Check: istiod proxy containers have ISTIO_META_NETWORK set to cluster1
✅ ISTIO_META_NETWORK Check: sidecar-injector ConfigMap template has ISTIO_META_NETWORK set to cluster1
✅ ISTIO_META_NETWORK Check: all ISTIO_META_NETWORK values match network label

If this check fails, set ISTIO_META_NETWORK on your istiod deployment to match the topology.istio.io/network label on the istio-system namespace, and update the sidecar-injector ConfigMap template accordingly.

Stale workload entries

In flat network setups, checks for any outdated workload entries that must be removed from the multicluster mesh. Stale workload entries might exist from pods that were deleted, but the autogenerated entries for those workloads were not correctly cleaned up. If you do not use a flat network topology, no autogenerated workload entries exist to be validated, and this check can be ignored.

Example verbose output for a non-flat network setup:

--- Stale Workloads Check ---

⚠  Stale Workloads Check: no autogenflat workload entries found

If you use a flat network topology, and this check fails with stale workload entries, run kubectl get workloadentries -n istio-system | grep autogenflat to list the autogenerated workload entries in the remote cluster, and compare the list to the output of kubectl get pods in the source cluster for those workloads. You can safely manually delete the stale workload entries in the remote cluster for pods that no longer exist in the source cluster, such as by running kubectl get workloadentries -n istio-system <entry_name>.

Missing local Segment resources

Checks for missing local Segment resources, which might cause auto-generated ServiceEntry resources that are received from a peered cluster to be silently dropped. If a remote cluster sends ServiceEntry resources for a Segment that does not exist locally, those entries are dropped without error. This check detects that condition and reports an actionable message for each rejected peer Segment.

Example verbose output:

--- Segment Readiness Check ---

✅ Segment Readiness Check: all peer Segments have matching local Segment resources

If this check reports missing Segment resources, create the corresponding Segment resource in the local cluster to match the one defined in the remote cluster.

Rejected peer Segment states

Checks for peer Segment resources that are in a rejected state due to hostname mismatches or overlapping Segment domains across clusters. Rejected segment states prevent the peering controller from federating workload entries for the affected services.

Example verbose output:

--- Peer Segment State Check ---

✅ Peer Segment State Check: no rejected peer Segments detected

If this check fails, review the Segment resources in each cluster for conflicting spec.domain values or mismatched hostnames, and ensure that Segment domains are unique across the multicluster mesh.

Hostname conflicts

Checks for hostname conflicts in auto-generated ServiceEntry resources by reading conflict annotations added by the peering controller. Hostname conflicts occur when two services in different clusters or namespaces resolve to the same hostname in the mesh, causing one ServiceEntry to override the other.

Example verbose output:

--- Hostname Conflict Check ---

✅ Hostname Conflict Check: no hostname conflicts detected in auto-generated ServiceEntry resources

If this check reports conflicts, review the conflicting services and adjust your Segment configuration to ensure each service resolves to a unique hostname across the mesh.

Metrics

You can also check metrics that are built into the Solo distribution of Istio to verify multiple aspects of the multicluster peering status.

Each peering metric has the labels source and peer, which appear as fields in the metric. The source is the local istiod instance in the cluster where the metric is emitted, and peer is the peered remote cluster. The convergence time metrics are important for understanding how quickly configuration propagates to peer clusters. A high convergence time can indicate slow propagation, connectivity issues, or that the peer or network is under load.

1. Port-forward to the istiod pod in each cluster to access its metrics endpoint.

   kubectl port-forward -n istio-system deploy/istiod 15014:15014 --context ${context1}

2. In a separate terminal, query the metrics endpoint and filter for peer metrics.

   curl -s http://localhost:15014/metrics | grep '^peer_'

3. Repeat for each cluster in the mesh, updating the --context flag.

The following peer metrics are available.

If you use Grafana to monitor Istio performance, you can also check out the Grafana dashboards in the Solo Communities of Practice (COP) repository. For example, you can use the istio-peering-dashboard to monitor and verify peering connection between clusters, and the istio-global-services-dashboard to monitor locality-aware traffic distribution and endpoint health across clusters, networks, zones, and regions.

Further debugging and observability

For additional guidance around observing your multicluster ambient mesh, check out the observability overview, which contains links to guides on using logs, metrics, and traces in your Istio environment.

For additional guidance around debugging your multicluster ambient mesh, check out the Istio troubleshooting guide.

ServiceMeshController reference

Review the commonly configured fields for the ServiceMeshController custom resource. For the full list of available options, see the ServiceMeshController API reference.

Advanced settings configuration

You can set advanced Istio configuration by creating a configmap. For example, you might need to specify settings for istiod such as discovery selectors, pod and service annotations, affinities, tolerations, or node selectors.

The following gloo-extensions-config example configmap sets all possible fields for demonstration purposes. Note that in some guides in this documentation set, Helm extension settings such as data.values.istiod are defined for specific settings in the configmap. However, these settings are used only when necessary, and are not recommended for other general use cases.

apiVersion: v1
kind: ConfigMap
metadata:
  name: gloo-extensions-config
  namespace: gloo-mesh
data:
  stable: |
    serviceMeshController:
      istiod:
        discoverySelectors:
          - matchLabels:
              foo: bar
        topology:
          affinity:
            podAntiAffinity:
              preferredDuringSchedulingIgnoredDuringExecution:
              - podAffinityTerm:
                  labelSelector:
                    matchExpressions:
                    - key: foo
                      operator: In
                      values:
                      - bar
                  topologyKey: foo.io/bar
                weight: 80
          nodeSelector:
            foo: bar
          tolerations:
            - key: t1
              operator: Equal
              value: v1
        deployment:
          podAnnotations:
            foo: bar
        serviceAnnotations:
          foo: bar
  beta: |
    serviceMeshController:
      cni:
        confDir: /foo/bar
        binDir: /foo/bar