Secure workload identites with SPIRE ENTERPRISE

Overview link

About the integration link

SPIRE offers robust workload attestation capabilities that provide significantly more controls around how, when, and if identities are granted to workloads. The Solo distribution of Istio includes Enterprise support for using SPIRE node agents (over an Envoy SDS socket) to attest and grant identities to the ambient mesh workloads they proxy. This allows Istio to use these identities for mTLS connections between the ambient mesh workloads.

With the SPIRE integration, the ztunnel can act as a trusted spire-agent delegate on the node by using the SPIRE DelegatedIdentity API. Ztunnel can integrate with SPIRE to leverage SPIRE’s existing node and workload attestation plugin framework directly, as well as request workload certificates that are issued by SPIRE on the basis of those attestations.

How it works link

Community Istio natively supports a SPIRE integration with the sidecar dataplane mode, in which you must mount sockets or volumes in every workload. However, Gloo Mesh’s support for SPIRE in the ambient dataplane mode functions much more simply. To enable the SPIRE integration with ambient, you only need to register your workloads with SPIRE, and then continue to label your service namespaces for the ambient dataplane mode as usual. Every ambient workload is automatically assigned a SPIRE-managed identity and uses that identity for mTLS, without the need to mount sockets or volumes in every workload.

In ambient, the Layer 4 node proxy, ztunnel, is responsible for capturing and encrypting all pod-to-pod traffic, and for managing workload identities. In the SPIRE-enabled ambient mode, ztunnel obtains those identities directly from the SPIRE agent that runs on the same node, and thus acts as a trusted delegate of SPIRE. However, note that the SPIRE agent attests the workloads, not ztunnel.

This allows the ambient dataplane to integrate with SPIRE’s delegation API as a trusted delegate, while leveraging SPIRE’s multifactor node and workload attestation plugin frameworks directly. The ambient dataplane can request workload certificates issued by SPIRE on the basis of those attestations.

Review the following sequence diagram that shows how SPIRE attestation in ambient works.

1. The ztunnel on the same node as the ambient-enrolled workload pod obtains the PID of the workload container in the pod.
2. The ztunnel then requests the SPIRE agent on the same node to attest the identity of the workload using its PID.
3. The SPIRE agent performs checks against the workload to determine whether it can grant the workload a trusted identity.
4. If the checks succeed, the SPIRE agent returns a certificate (SPIFFE x509 SVID) to the ztunnel for the workload.
5. The ztunnel enforces mTLS connections for the workload pod using the SPIRE-issued certificate.
6. The workload pod can then make mTLS-secure connections to other ambient workloads.

To learn more about SPIRE, and how the SPIRE integration with Istio works in Gloo Mesh, check out this blog post.

Single cluster link

Deploy an ambient mesh that uses SPIRE workload identity attestation.

Set up tools link

Before you begin, set up the following tools and save details in environment variables.

1. Set your Enterprise-level license for Gloo Mesh as an environment variable. If you do not have one, contact an account representative. If you prefer to specify license keys in a secret instead, see Licensing.

     export GLOO_MESH_LICENSE_KEY=<enterprise_license_key>
     

2. Save the name of your cluster, which you use in the SPIRE trust domain settings.

     export CLUSTER_NAME=<cluster_name>
     

3. Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions table, and saving it in an environment variable. Note that the Gloo Operator installs the Solo distribution of Istio by default for the version you specify, so neither the -solo image tag nor the repo key are required.

     export ISTIO_VERSION=1.25.5-patch1
     

4. Make sure that you have the OpenSSL version of openssl, not LibreSSL. The openssl version must be at least 1.1.

   1. Check your openssl version. If you see LibreSSL in the output, continue to the next step.

        openssl version
        

   2. Install the OpenSSL version (not LibreSSL). For example, you might use Homebrew.

        brew install openssl
        

   3. Review the output of the OpenSSL installation for the path of the binary file. You can choose to export the binary to your path, or call the entire path whenever the following steps use an openssl command.
      • For example, openssl might be installed along the following path: /usr/local/opt/openssl@3/bin/
      • To run commands, you can append the path so that your terminal uses this installed version of OpenSSL, and not the default LibreSSL. /usr/local/opt/openssl@3/bin/openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650...

Prepare SPIRE certificates link

Create the root and intermediate CA for the SPIRE server. The SPIRE server later uses these CAs to create certificates for any attested workloads.

1. Create a directory for the certificates, and save the CA certificate configurations.

     mkdir -p certs/{root-ca,intermediate-ca}
   cd certs
   
   cat >root-ca.cnf <<EOF
   [req]
   distinguished_name = req_distinguished_name
   req_extensions = v3_req
   prompt = no
   
   [req_distinguished_name]
   CN = SPIRE Root CA
   
   [v3_req]
   keyUsage = critical, keyCertSign, cRLSign
   basicConstraints = critical, CA:true, pathlen:2
   subjectKeyIdentifier = hash
   EOF
   
   cat >intermediate-ca.cnf <<EOF
   [req]
   distinguished_name = req_distinguished_name
   req_extensions = v3_req
   prompt = no
   
   [req_distinguished_name]
   CN = SPIRE Intermediate CA
   
   [v3_req]
   keyUsage = critical, keyCertSign, cRLSign
   basicConstraints = critical, CA:true, pathlen:1
   subjectKeyIdentifier = hash
   EOF
     

2. Create the root CA and intermediate CA, and sign the intermediate CA with the root CA.

     # Create root CA
   openssl genrsa -out root-ca/root-ca.key 2048
   openssl req -new -x509 -key root-ca/root-ca.key -out root-ca/root-ca.crt -config root-ca.cnf -days 3650
   
   # Create intermediate CA
   openssl genrsa -out intermediate-ca/ca.key 2048
   openssl req -new -key intermediate-ca/ca.key -out intermediate-ca/ca.csr -config intermediate-ca.cnf -subj "/CN=SPIRE INTERMEDIATE CA"
   
   # Sign CSR with root CA
   openssl x509 -req -in intermediate-ca/ca.csr -CA root-ca/root-ca.crt -CAkey root-ca/root-ca.key -CAcreateserial \
     -out intermediate-ca/ca.crt -days 1825 -extensions v3_req -extfile intermediate-ca.cnf
   
   # Create the bundle file (intermediate + root)
   cat intermediate-ca/ca.crt root-ca/root-ca.crt > intermediate-ca/ca-chain.pem
   
   # Create the root CA bundle
   cp root-ca/root-ca.crt root-ca-bundle.pem
     

3. Create the spire-server namespace, and issue the certificates as secrets ready to be mounted onto SPIRE.

     kubectl create namespace spire-server
   kubectl create secret generic spiffe-upstream-ca \
     --from-file=tls.crt=certs/intermediate-ca/ca.crt \
     --from-file=tls.key=certs/intermediate-ca/ca.key \
     --from-file=bundle.crt=certs/intermediate-ca/ca-chain.pem \
     -n spire-server
     

Install SPIRE link

Use Helm to deploy SPIRE in each cluster.

1. Add and update the SPIRE Helm repo.

     helm repo add spire https://spiffe.github.io/helm-charts-hardened/
   helm repo update spire
     

2. Create the SPIRE CRDs and SPIRE Helm releases.

     helm upgrade -i spire-crds spire/spire-crds \
   --namespace spire-server \
   --create-namespace \
   --version 0.5.0 \
   --wait
   
   helm upgrade -i spire spire/spire \
   --namespace spire-server \
   --version 0.24.2 \
   -f - <<EOF
   # Source https://github.com/solo-io/istio/blob/build/release-1.23/tools/install-spire.sh
   global:
     spire:
       trustDomain: ${CLUSTER_NAME}
   spire-agent:
       authorizedDelegates:
           - "spiffe://${CLUSTER_NAME}/ns/istio-system/sa/ztunnel"
       sockets:
           admin:
               enabled: true
               mountOnHost: true
           hostBasePath: /run/spire/agent/sockets
       tolerations:
         - effect: NoSchedule
           operator: Exists
         - key: CriticalAddonsOnly
           operator: Exists
         - effect: NoExecute
           operator: Exists
   spire-server:
     upstreamAuthority:
       disk:
         enabled: true
         secret:
           create: false
           name: "spiffe-upstream-ca"
   
   spiffe-csi-driver:
       tolerations:
         - effect: NoSchedule
           operator: Exists
         - key: CriticalAddonsOnly
           operator: Exists
         - effect: NoExecute
           operator: Exists
   EOF
     

3. Verify that the SPIRE server is deployed.

     kubectl -n spire-server wait --for=condition=Ready pods --all
     

4. Configure SPIRE to issue certificates for the ambient mesh workloads.

     kubectl apply -f - <<EOF
   # Source https://github.com/solo-io/istio/blob/build/release-1.23/tools/install-spire.sh
   ---
   # ClusterSPIFFEID for ztunnel
   apiVersion: spire.spiffe.io/v1alpha1
   kind: ClusterSPIFFEID
   metadata:
     name: istio-ztunnel-reg
   spec:
     spiffeIDTemplate: "spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}"
     podSelector:
       matchLabels:
         app: "ztunnel"
   ---
   # ClusterSPIFFEID for waypoints
   apiVersion: spire.spiffe.io/v1alpha1
   kind: ClusterSPIFFEID
   metadata:
     name: istio-waypoint-reg
   spec:
     spiffeIDTemplate: "spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}"
     podSelector:
       matchLabels:
         istio.io/gateway-name: waypoint
   ---
   # ClusterSPIFFEID for workloads
   apiVersion: spire.spiffe.io/v1alpha1
   kind: ClusterSPIFFEID
   metadata:
     name: istio-ambient-reg
   spec:
     spiffeIDTemplate: "spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}"
     podSelector:
       matchLabels:
         istio.io/dataplane-mode: ambient
   EOF
     

Any workloads that you later deploy to the ambient mesh will now be able to get mTLS certificates from SPIRE.

Install an ambient mesh with SPIRE enabled link

Use the Gloo Operator to create the ambient mesh components, with the SPIRE integration enabled.

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. Note that if you already installed Gloo Mesh, you can optionally reference the secret that Gloo Mesh (OSS APIs) automatically creates for your license in the –set manager.env.SOLO_ISTIO_LICENSE_KEY_SECRET_REF=gloo-mesh/license-keys flag instead.

     helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
     --version 0.4.3 \
     -n gloo-mesh \
     --create-namespace \
     --set manager.env.SOLO_ISTIO_LICENSE_KEY=${GLOO_MESH_LICENSE_KEY}
     

2. Verify that the operator pod is running.

     kubectl get pods -n gloo-mesh -l app.kubernetes.io/name=gloo-operator
     

   Example output:

     gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s
     

3. Apply the following configmap and ServiceMeshController for the Gloo Operator to enable the SPIRE integration and deploy an ambient mesh.

     kubectl apply -n gloo-mesh -f -<<EOF
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: gloo-extensions-config
     namespace: gloo-mesh
   data:
     values.istiod: |
       gateways:
         spire:
           workloads: true
     values.istio-ztunnel: |
       spire:
         enabled: true
   ---
   apiVersion: operator.gloo.solo.io/v1
   kind: ServiceMeshController
   metadata:
     name: managed-istio
     labels:
       app.kubernetes.io/name: managed-istio
   spec:
     cluster: $CLUSTER_NAME # Matches the custom trustDomain in SPIRE settings
     dataplaneMode: Ambient
     installNamespace: istio-system
     version: ${ISTIO_VERSION}
   EOF
     

   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 istiod control plane, Istio CNI, and ztunnel pods are running.

     kubectl get pods -n istio-system
     

   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
     

5. Apply the CRDs for the Kubernetes Gateway API to your cluster, which are required to create components such as waypoint proxies for L7 traffic policies, gateways with the Gateway resource, and more.

     kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml
     

Deploy services to the ambient mesh link

Add apps to the ambient mesh. Note that whenever you label a workload to add it to your ambient mesh, the ztunnel on the same node requests that the SPIRE agent performs workload attestation. The provided certificate for the workload enables it to initiate mTLS communication within the mesh.

Multicluster link

Deploy a multicluster ambient mesh that uses SPIRE workload identity attestation.

Set up tools link

Before you begin, set up the following tools and save details in environment variables.

1. Set your Enterprise-level license for Gloo Mesh as an environment variable. If you do not have one, contact an account representative. If you prefer to specify license keys in a secret instead, see Licensing.

     export GLOO_MESH_LICENSE_KEY=<enterprise_license_key>
     

2. Save the names and contexts of your clusters. The example steps in this guide assume one management cluster that the Gloo management plane is installed in, and two registered workload clusters where you want to install ambient meshes.

   1. Set the names of your clusters from your infrastructure provider.

        export MGMT_CLUSTER=<mgmt-cluster-name>
      export REMOTE_CLUSTER1=<workload-cluster1-name>
      export REMOTE_CLUSTER2=<workload-cluster2-name>
        

   2. Save the kubeconfig contexts for your clusters. Run kubectl config get-contexts, look for your cluster in the CLUSTER column, and get the context name in the NAME column. Note: Do not use context names with underscores. The generated certificate that connects workload clusters to the management cluster uses the context name as a SAN specification, and underscores in SAN are not FQDN compliant. You can rename a context by running kubectl config rename-context "<oldcontext>" <newcontext>.

        export MGMT_CONTEXT=<management-cluster-context>
      export REMOTE_CONTEXT1=<workload-cluster1-context>
      export REMOTE_CONTEXT2=<workload-cluster2-context>
        

3. Save the details for the version of the Solo distribution of Istio that you want to install.

   1. Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions. In Gloo Mesh (OSS APIs) version 2.7 and later, multicluster setups require version 1.24.3 or later.
   2. Set environment variables for the Solo distribution of Istio that you want to install. You can find these values in the Istio images built by Solo.io support article.

        # Solo distribution of Istio patch version
      # in the format 1.x.x, with no tags
      export ISTIO_VERSION=<istio_version>
      export ISTIO_IMAGE=${ISTIO_VERSION}-solo
      # Repo key for the minor version of the Solo distribution of Istio
      # This is the 12-character hash at the end of the repo URL: 'us-docker.pkg.dev/gloo-mesh/istio-<repo-key>'
      export REPO_KEY=<repo_key>
        

4. 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/gloo-mesh-use-cases/main/gloo-mesh/install-istioctl.sh)
   export PATH=${HOME}/.istioctl/bin:${PATH}
     

5. Make sure that you have the OpenSSL version of openssl, not LibreSSL. The openssl version must be at least 1.1.

   1. Check your openssl version. If you see LibreSSL in the output, continue to the next step.

        openssl version
        

   2. Install the OpenSSL version (not LibreSSL). For example, you might use Homebrew.

        brew install openssl
        

   3. Review the output of the OpenSSL installation for the path of the binary file. You can choose to export the binary to your path, or call the entire path whenever the following steps use an openssl command.
      • For example, openssl might be installed along the following path: /usr/local/opt/openssl@3/bin/
      • To run commands, you can append the path so that your terminal uses this installed version of OpenSSL, and not the default LibreSSL. /usr/local/opt/openssl@3/bin/openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650...

Prepare SPIRE certificates link

Create the root and one intermediate CA for the SPIRE server in each cluster. The SPIRE server later uses these CAs to create certificates for any attested workloads.

1. Create a directory for the certificates, and save the CA certificate configurations.

     mkdir -p certs/{root-ca,${REMOTE_CLUSTER1},${REMOTE_CLUSTER2}}
   cd certs
   
   cat >root-ca.cnf <<EOF
   [req]
   distinguished_name = req_distinguished_name
   req_extensions = v3_req
   prompt = no
   
   [req_distinguished_name]
   CN = SPIRE Root CA
   
   [v3_req]
   keyUsage = critical, keyCertSign, cRLSign
   basicConstraints = critical, CA:true, pathlen:2
   subjectKeyIdentifier = hash
   EOF
   
   cat >intermediate-ca.cnf <<EOF
   [req]
   distinguished_name = req_distinguished_name
   req_extensions = v3_req
   prompt = no
   
   [req_distinguished_name]
   CN = SPIRE Intermediate CA
   
   [v3_req]
   keyUsage = critical, keyCertSign, cRLSign
   basicConstraints = critical, CA:true, pathlen:1
   subjectKeyIdentifier = hash
   EOF
     

2. Create the root CA. Then create one intermediate CA for each workload cluster, and use the root CA to sign both intermediate CAs.

     # Create root CA
   openssl genrsa -out root-ca/root-ca.key 2048
   openssl req -new -x509 -key root-ca/root-ca.key -out root-ca/root-ca.crt -config root-ca.cnf -days 3650
   
   # Create cluster 1 intermediate CA
   openssl genrsa -out ${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.key 2048
   openssl req -new -key ${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.key -out ${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.csr -config intermediate-ca.cnf -subj "/CN=SPIRE ${REMOTE_CLUSTER1} CA"
   # Sign cluster 1 CSR with root CA
   openssl x509 -req -in ${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.csr -CA root-ca/root-ca.crt -CAkey root-ca/root-ca.key -CAcreateserial \
     -out ${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.crt -days 1825 -extensions v3_req -extfile intermediate-ca.cnf
   
   # Create cluster 2 intermediate CA
   openssl genrsa -out ${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.key 2048
   openssl req -new -key ${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.key -out ${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.csr -config intermediate-ca.cnf -subj "/CN=SPIRE ${REMOTE_CLUSTER2} CA"
   # Sign cluster 2 CSR with root CA
   openssl x509 -req -in ${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.csr -CA root-ca/root-ca.crt -CAkey root-ca/root-ca.key -CAcreateserial \
     -out ${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.crt -days 1825 -extensions v3_req -extfile intermediate-ca.cnf
   
   # Create the bundle file for cluster 1 (intermediate + root)
   cat ${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.crt root-ca/root-ca.crt > ${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca-chain.pem
   
   # Create the bundle file for cluster 2 (intermediate + root)
   cat ${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.crt root-ca/root-ca.crt > ${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca-chain.pem
   
   # Create the root CA bundle
   cp root-ca/root-ca.crt root-ca-bundle.pem
     

3. Create the spire-server namespace in each cluster, and issue the certificates as secrets ready to be mounted onto SPIRE.

     kubectl --context=${REMOTE_CONTEXT1} create namespace spire-server
   kubectl --context=${REMOTE_CONTEXT1} create secret generic spiffe-upstream-ca \
     --from-file=tls.crt=certs/${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.crt \
     --from-file=tls.key=certs/${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca.key \
     --from-file=bundle.crt=certs/${REMOTE_CLUSTER1}/${REMOTE_CLUSTER1}-ca-chain.pem \
     -n spire-server
   
   kubectl --context=${REMOTE_CONTEXT2} create namespace spire-server
   kubectl --context=${REMOTE_CONTEXT2} create secret generic spiffe-upstream-ca \
     --from-file=tls.key=certs/${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.key \
     --from-file=tls.crt=certs/${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca.crt \
     --from-file=bundle.crt=certs/${REMOTE_CLUSTER2}/${REMOTE_CLUSTER2}-ca-chain.pem \
     -n spire-server
     

Install SPIRE link

Use Helm to deploy SPIRE in each cluster.

1. Add and update the SPIRE Helm repo.

     helm repo add spire https://spiffe.github.io/helm-charts-hardened/
   helm repo update spire
     

2. Create the SPIRE CRDs Helm release in each cluster.

     helm upgrade --kube-context=${REMOTE_CONTEXT1} -i spire-crds spire/spire-crds \
   --namespace spire-server \
   --create-namespace \
   --version 0.5.0 \
   --wait
   
   helm upgrade --kube-context=${REMOTE_CONTEXT2} -i spire-crds spire/spire-crds \
   --namespace spire-server \
   --create-namespace \
   --version 0.5.0 \
   --wait
     

3. Create the SPIRE Helm release in each cluster.

     helm upgrade --kube-context=${REMOTE_CONTEXT1} -i spire spire/spire \
   --namespace spire-server \
   --version 0.24.2 \
   -f - <<EOF
   # Source https://github.com/solo-io/istio/blob/build/release-1.23/tools/install-spire.sh
   global:
     spire:
       trustDomain: ${REMOTE_CLUSTER1}
   spire-agent:
       authorizedDelegates:
           - "spiffe://${REMOTE_CLUSTER1}/ns/istio-system/sa/ztunnel"
       sockets:
           admin:
               enabled: true
               mountOnHost: true
           hostBasePath: /run/spire/agent/sockets
       tolerations:
         - effect: NoSchedule
           operator: Exists
         - key: CriticalAddonsOnly
           operator: Exists
         - effect: NoExecute
           operator: Exists
   spire-server:
     upstreamAuthority:
       disk:
         enabled: true
         secret:
           create: false
           name: "spiffe-upstream-ca"
   
   spiffe-csi-driver:
       tolerations:
         - effect: NoSchedule
           operator: Exists
         - key: CriticalAddonsOnly
           operator: Exists
         - effect: NoExecute
           operator: Exists
   EOF
   
   helm upgrade --kube-context=${REMOTE_CONTEXT2} -i spire spire/spire \
   --namespace spire-server \
   --version 0.24.2 \
   -f - <<EOF
   # Source https://github.com/solo-io/istio/blob/build/release-1.23/tools/install-spire.sh
   global:
     spire:
       trustDomain: ${REMOTE_CLUSTER2}
   spire-agent:
       authorizedDelegates:
           - "spiffe://${REMOTE_CLUSTER2}/ns/istio-system/sa/ztunnel"
       sockets:
           admin:
               enabled: true
               mountOnHost: true
           hostBasePath: /run/spire/agent/sockets
       tolerations:
         - effect: NoSchedule
           operator: Exists
         - key: CriticalAddonsOnly
           operator: Exists
         - effect: NoExecute
           operator: Exists
   spire-server:
     upstreamAuthority:
       disk:
         enabled: true
         secret:
           create: false
           name: "spiffe-upstream-ca"
   
   spiffe-csi-driver:
       tolerations:
         - effect: NoSchedule
           operator: Exists
         - key: CriticalAddonsOnly
           operator: Exists
         - effect: NoExecute
           operator: Exists
   EOF
     

4. Verify that the SPIRE servers are deployed.

     kubectl --context=${REMOTE_CONTEXT1} -n spire-server wait --for=condition=Ready pods --all
   kubectl --context=${REMOTE_CONTEXT2} -n spire-server wait --for=condition=Ready pods --all
     

5. Configure SPIRE to issue certificates for the ambient mesh workloads.

     cat >cluster-spiffe-id.yaml <<EOF
   # Source https://github.com/solo-io/istio/blob/build/release-1.23/tools/install-spire.sh
   ---
   # ClusterSPIFFEID for ztunnel
   apiVersion: spire.spiffe.io/v1alpha1
   kind: ClusterSPIFFEID
   metadata:
     name: istio-ztunnel-reg
   spec:
     spiffeIDTemplate: "spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}"
     podSelector:
       matchLabels:
         app: "ztunnel"
   ---
   # ClusterSPIFFEID for waypoints
   apiVersion: spire.spiffe.io/v1alpha1
   kind: ClusterSPIFFEID
   metadata:
     name: istio-waypoint-reg
   spec:
     spiffeIDTemplate: "spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}"
     podSelector:
       matchLabels:
         istio.io/gateway-name: waypoint
   ---
   # ClusterSPIFFEID for workloads
   apiVersion: spire.spiffe.io/v1alpha1
   kind: ClusterSPIFFEID
   metadata:
     name: istio-ambient-reg
   spec:
     spiffeIDTemplate: "spiffe://{{ .TrustDomain }}/ns/{{ .PodMeta.Namespace }}/sa/{{ .PodSpec.ServiceAccountName }}"
     podSelector:
       matchLabels:
         istio.io/dataplane-mode: ambient
   EOF
   
   kubectl --context=${REMOTE_CONTEXT1} apply -f cluster-spiffe-id.yaml
   kubectl --context=${REMOTE_CONTEXT2} apply -f cluster-spiffe-id.yaml
     

Any workloads that you later deploy to the ambient mesh will now be able to get mTLS certificates from SPIRE.

Create a shared root of trust for istiod link

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 ${REMOTE_CONTEXT1} ${REMOTE_CLUSTER1}
create_cacerts_secret ${REMOTE_CONTEXT2} ${REMOTE_CLUSTER2}

cd ../..
  

Install ambient meshes with SPIRE enabled link

In each cluster, use the Gloo Operator to create the ambient mesh components, with the SPIRE integration enabled.

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. Note that if you already installed Gloo Mesh, you can optionally reference the secret that Gloo Mesh (OSS APIs) automatically creates for your license in the –set manager.env.SOLO_ISTIO_LICENSE_KEY_SECRET_REF=gloo-mesh/license-keys flag instead.

     helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
     --version 0.4.3 \
     -n gloo-mesh \
     --create-namespace \
     --kube-context ${REMOTE_CONTEXT1} \
     --set manager.env.SOLO_ISTIO_LICENSE_KEY=${GLOO_MESH_LICENSE_KEY}
   
   helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
     --version 0.4.3 \
     -n gloo-mesh \
     --create-namespace \
     --kube-context ${REMOTE_CONTEXT2} \
     --set manager.env.SOLO_ISTIO_LICENSE_KEY=${GLOO_MESH_LICENSE_KEY}
     

2. Verify that the operator pod is running.

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

   Example output:

     gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s
     

3. Apply the following configmap and ServiceMeshController for the Gloo Operator to enable the SPIRE integartion and deploy an ambient mesh.

     kubectl apply -n gloo-mesh --context ${REMOTE_CONTEXT1} -f -<<EOF
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: gloo-extensions-config
     namespace: gloo-mesh
   data:
     values.istiod: |
       gateways:
         spire:
           workloads: true
     values.istio-ztunnel: |
       spire:
         enabled: true
   ---
   apiVersion: operator.gloo.solo.io/v1
   kind: ServiceMeshController
   metadata:
     name: managed-istio
     labels:
       app.kubernetes.io/name: managed-istio
   spec:
     cluster: ${REMOTE_CLUSTER1}
     network: ${REMOTE_CLUSTER1}
     dataplaneMode: Ambient
     installNamespace: istio-system
     version: ${ISTIO_VERSION}
   EOF
   
   kubectl apply -n gloo-mesh --context ${REMOTE_CONTEXT2} -f -<<EOF
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: gloo-extensions-config
     namespace: gloo-mesh
   data:
     values.istiod: |
       gateways:
         spire:
           workloads: true
     values.istio-ztunnel: |
       spire:
         enabled: true
   ---
   apiVersion: operator.gloo.solo.io/v1
   kind: ServiceMeshController
   metadata:
     name: managed-istio
     labels:
       app.kubernetes.io/name: managed-istio
   spec:
     cluster: ${REMOTE_CLUSTER2}
     network: ${REMOTE_CLUSTER2}
     dataplaneMode: Ambient
     installNamespace: istio-system
     version: ${ISTIO_VERSION}
   EOF
     

   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 istiod control plane, Istio CNI, and ztunnel pods are running.

     kubectl get pods -n istio-system --context ${REMOTE_CONTEXT1}
   kubectl get pods -n istio-system --context ${REMOTE_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
     

Link clusters link

Create east-west gateways so that traffic requests can be routed cross-cluster. Then, link clusters to enable cross-cluster service discovery.

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

2. Create an east-west gateway in the istio-eastwest namespace. An east-west gateway facilitates traffic between services in each cluster in your multicluster mesh.

     for context in ${REMOTE_CONTEXT1} ${REMOTE_CONTEXT2}; do
     kubectl create namespace istio-eastwest --context ${context}
     istioctl multicluster expose --namespace istio-eastwest --context ${context} --generate > ew-gateway.yaml
     kubectl apply -f ew-gateway.yaml --context ${context}
   done
     

3. Verify that the east-west gateways are successfully deployed.

     kubectl get pods -n istio-eastwest --context ${REMOTE_CONTEXT1}
   kubectl get pods -n istio-eastwest --context ${REMOTE_CONTEXT2}
     

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

   1. Link clusters to enable cross-cluster service discovery and allow traffic to be routed through east-west gateways across clusters. The steps vary based on whether you have access to the kubeconfig files for each cluster.

      1. Verify that the contexts for the clusters that you want to include in the multicluster mesh are listed in your kubeconfig file.

           kubectl config get-contexts
           

         • In the output, note the names of the cluster contexts, which you use in the next step to link the clusters.
         • If you have multiple kubeconfig files, you can generate a merged kubeconfig file by running the following command.

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

      2. Using the names of the cluster contexts, link the clusters so that they can communicate. Note that you can either link the clusters bi-directionally or asymmetrically. In a standard bi-directional setup, services in any of the linked clusters can send requests to and receive requests from the services in any of the other linked clusters. In an asymmetrical setup, you allow one cluster to send requests to another cluster, but the other cluster cannot send requests back to the first cluster.

         • 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>,<context3>"
             

           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.

           Example output for two clusters:

             Gateway istio-eastwest/istio-remote-peer-cluster1 applied to cluster "<cluster2_context>" pointing to cluster "<cluster1_context>" (network "cluster1")
           Gateway istio-eastwest/istio-remote-peer-cluster2 applied to cluster "<cluster1_context>" pointing to cluster "<cluster2_context>" (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.

             istioctl multicluster link --namespace istio-eastwest --from <context1> --to <context2>
             

           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.

           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 cluster1 --to cluster2
             

           Example output:

             Gateway istio-eastwest/istio-remote-peer-cluster2 applied to cluster "<cluster1_context>" pointing to cluster "<cluster2_context>" (network "cluster2")
             

      If you do not have access to all kubeconfig files for the clusters you want to link, or if you cannot combine the cluster contexts into one kubeconfig file, you can link the clusters by declaratively creating istio-remote peer gateways.

      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.

      Bi-directional: You can 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.

      4. 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 $REMOTE_CONTEXT1 -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
         export CLUSTER2_EW_ADDRESS=$(kubectl get svc -n istio-eastwest istio-eastwest --context $REMOTE_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"
           

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

           kubectl apply --context $REMOTE_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: $REMOTE_CLUSTER2
           labels:
             topology.istio.io/network: $REMOTE_CLUSTER2
           name: istio-remote-peer-$REMOTE_CLUSTER2
           namespace: istio-eastwest
         spec:
           addresses:
           - type: IPAddress
             value: $CLUSTER2_EW_ADDRESS
           gatewayClassName: istio-remote
           listeners:
           - name: cross-network
             port: 15008
             protocol: HBONE
             tls:
               mode: Passthrough
           - name: xds-tls
             port: 15012
             protocol: TLS
             tls:
               mode: Passthrough
         EOF
         
         kubectl apply --context $REMOTE_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: $REMOTE_CLUSTER1
           labels:
             topology.istio.io/network: $REMOTE_CLUSTER1
           name: istio-remote-peer-$REMOTE_CLUSTER1
           namespace: istio-eastwest
         spec:
           addresses:
           - type: IPAddress
             value: $CLUSTER1_EW_ADDRESS
           gatewayClassName: istio-remote
           listeners:
           - name: cross-network
             port: 15008
             protocol: HBONE
             tls:
               mode: Passthrough
           - name: xds-tls
             port: 15012
             protocol: TLS
             tls:
               mode: Passthrough
         EOF
           

      Asymmetrical: You can 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.

      6. 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 $REMOTE_CONTEXT2 -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
         
         echo "Cluster2 east-west gateway: $CLUSTER2_EW_ADDRESS"
           

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

           kubectl apply --context $REMOTE_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: $REMOTE_CLUSTER2
           labels:
             topology.istio.io/network: $REMOTE_CLUSTER2
           name: istio-remote-peer-$REMOTE_CLUSTER2
           namespace: istio-eastwest
         spec:
           addresses:
           - type: IPAddress
             value: $CLUSTER2_EW_ADDRESS
           gatewayClassName: istio-remote
           listeners:
           - name: cross-network
             port: 15008
             protocol: HBONE
             tls:
               mode: Passthrough
           - name: xds-tls
             port: 15012
             protocol: TLS
             tls:
               mode: Passthrough
         EOF
           

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

        istioctl proxy-status --context $REMOTE_CONTEXT1
      istioctl proxy-status --context $REMOTE_CONTEXT2
        

      Example output for cluster-1, in which you can verify that the istiod control plane for cluster-2 is listed:

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

Deploy services to the multicluster mesh link

Add apps to the ambient mesh. This includes labeling services so that they are included in the ambient mesh, and making the services available across your linked cluster setup.

Note that whenever you label a workload to add it to your ambient mesh, the ztunnel on the same node requests that the SPIRE agent performs workload attestation. The provided certificate for the workload enables it to initiate mTLS communication within the mesh.

Optional: Validate your multicluster setup link

Both before and after you link clusters into a multicluster mesh, you can use the istioctl multicluster check command, along with other observability checks, to verify multiple aspects of multicluster ambient mesh support and status.

For example, 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>,<context3>"
  

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

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 Enterpise level license for Gloo Mesh.

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.

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.

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.

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.

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.

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.

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