Alauda Service Mesh v2 Docs
  • English

    • Migrating a single-network mesh

    The clusters of a single-network mesh share one flat pod network. A proxy reaches a workload of another cluster by its pod address, and the mesh has no east-west gateway. This document lists what differs from Migrating a multi-network mesh; everything else is identical to Migrating a single-cluster mesh, applied per cluster.

    Confirm the topology first, see Determine the network topology.

    The blocks below act on one cluster and address it as ${CTX}. Set it before the first of them, and again for the next cluster, see Address one cluster at a time:

    export CTX="${CTX_CLUSTER1}"
    Never change the network topology during the migration

    Throughout the migration, keep every network setting of Mesh v2 identical to Mesh v1. Never add the topology.istio.io/network label to the istio-system namespace, and never set spec.values.global.network on Mesh v2 to a value that differs from Mesh v1. Otherwise the two control planes disagree about which network each endpoint belongs to: Mesh v2 rewrites remote endpoints to east-west gateway addresses that do not exist, and cross-cluster traffic fails.

    While both generations serve the same mesh, they have to agree on which network an endpoint belongs to. The network comes from spec.values.global.network of each control plane and from the topology.istio.io/network label on the istio-system namespace and on the pods — and that namespace label is read by both generations. Migrating the control plane and changing the topology are two changes of their own; make one at a time.

    TOC

    Differences from the multi-network procedureVerificationAfter the migration

    Differences from the multi-network procedure

    PhaseMulti-networkSingle network
    Phase 0Record the mesh identity and the east-west gateways of every clusterThe same, plus confirm that pods of one cluster reach pods of the other directly; network has the same value on every cluster, and there is no east-west gateway to record or back up
    Phase 2Each Istio resource carries the network of its clusterThe network recorded from Mesh v1, which is the same value on every cluster. The remote secrets are reused as they are, exactly as in a multi-network mesh
    Phase 2 (after)Deploy a Mesh v2 east-west gateway per clusterSkipped: the mesh has no east-west gateway
    Phase 3Check the cross-cluster endpoints after each namespaceThe same check, plus the assertion below that remote endpoints stay pod addresses
    Phase 5Detach the east-west gateway service before the Mesh v1 control plane is deletedNot applicable. The north-south gateway services are detached as in a single-cluster mesh

    Phase 1 and Phase 4 are the same as for a multi-network mesh: Kiali covers every cluster, and the north-south gateways are migrated per cluster.

    Phase 6 is the same as for a multi-network mesh: each cluster gets its own intermediate certificate, the mesh uses one tracing index family, and the collector service is declared cluster-local so that every proxy exports to the collector of its own cluster. The reason differs. In this topology the collector of the other cluster is reachable, so spans sent there would arrive and both collectors write into the same index family — traces stay complete either way. Keeping the exports inside the cluster only avoids sending them across the cluster boundary for nothing. Check it on any proxy:

    istioctl --context "${CTX}" proxy-config endpoint "deploy/${WORKLOAD}.${MESH_NAMESPACE}" \
  --cluster "outbound|4317||otel-collector.jaeger-system.svc.cluster.local"

    One endpoint, the collector of the local cluster.

    Verification

    Check the remote endpoints of a service that has workloads in both clusters, from a proxy of each generation while they coexist, and again after the migration. The workload and the service are the ones named in The cross-cluster probe, and TARGET_SERVICE is the fully qualified name — the short name matches no Envoy cluster and prints an empty table:

    istioctl --context "${CTX}" proxy-config endpoint "deploy/${CLIENT}.${MESH_NAMESPACE}" \
  --cluster "outbound|${APP_PORT}||${TARGET_SERVICE}"

    Every endpoint is a pod address of one of the clusters. An address on port 15443 means that a control plane treats the other cluster as a separate network and is looking for an east-west gateway: check spec.values.global.network of both Istio resources and the labels of the istio-system namespaces.

    • The cross-cluster path serves traffic in both directions, in every combination of generations: the probes report OK, and rq_success grows on the endpoints that belong to the other cluster.
    • The istio-system namespace of every cluster carries no topology.istio.io/network label, before, during and after the migration.
    • The network, meshID and cluster name of each Istio resource are field by field what Mesh v1 had.

    After the migration

    The mesh stays single network: Mesh v2 supports this topology the same way Mesh v1 did, and nothing in the migration changes it.

    Read the migrated mesh in the traffic graph of Kiali, as described in After the migration. The clusters are drawn separately here as well, and the edges between them are the calls that use a pod address of the other cluster.