Cilium Cluster Mesh Explained: Multi-Cluster Networking

Updated on Oct 12, 2026

9 min read

Cilium Cluster Mesh lets teams connect independent Kubernetes clusters so selected workloads can communicate across cluster boundaries. Platform engineers use it when separate clusters need to share services without turning them into one Kubernetes control plane. This explainer covers its data path, service discovery, security boundaries, prerequisites, and a practical setup workflow.

What Is Cilium Cluster Mesh?

Cilium is an open-source networking, observability, and security project that uses eBPF in its Linux datapath. Cilium’s project site describes that broader scope; Cluster Mesh is the feature for connecting multiple Cilium-managed Kubernetes clusters and sharing selected network state between them.

Each cluster keeps its own Kubernetes API server and schedules its own workloads. Cluster Mesh coordinates information Cilium needs to make cross-cluster communication possible, including endpoint and identity data. A workload can then reach a service whose ready endpoints include pods in another participating cluster, subject to routing and policy.

This is a networking capability, not a way to combine clusters into one administrative domain. Kubernetes objects are not generally copied between clusters, and Cluster Mesh does not decide where workloads should run. For the underlying pod interfaces, routing, and CNI responsibilities, see the container networking guide and the Kubernetes architecture explainer.

The Problem Multi-Cluster Networking Solves

Organizations split workloads across clusters for reasons such as regional placement, isolation, capacity, staged upgrades, or separate teams and environments. But this separation creates practical gaps: a client in one cluster may not be able to route to a pod in another, service names are normally scoped to a cluster, and security policy needs to distinguish remote identities without depending on unstable pod addresses.

One option is to expose an application through an external load balancer or gateway and make other clusters call that endpoint. This is often appropriate for public APIs or intentionally narrow integration points, but it adds an ingress path and may not fit east-west traffic between internal services. Another option is to build custom DNS, routing, and failover mechanisms. Those can work, but teams then own the consistency and failure behavior themselves.

Cluster Mesh supplies a Cilium-native way to make selected services and identities visible across clusters. It does not remove the need to design application-level resilience, data replication, or access control.

How Cilium Cluster Mesh Works

Each cluster runs its own Cilium agents and local Kubernetes control plane. Cluster Mesh connects the Cilium control components so they can exchange the state needed for multi-cluster networking. The data plane remains distributed: packets are forwarded by Cilium on the participating nodes over the network between clusters.

For a global service, the service is declared in participating clusters and Cilium learns the eligible backends. A client can use the service’s stable identity while the datapath selects among local and remote endpoints. The Cilium global services documentation describes the shared-service model, while its Multi-Cluster Services API documentation explains the Kubernetes ServiceExport and ServiceImport approach. Which interface to use depends on the integration and operational conventions in your environment.

The packet still needs a valid route between the selected nodes. Cilium may use the datapath and routing mode configured for the clusters, but Cluster Mesh does not create physical connectivity or resolve conflicting network plans. Node reachability, firewall rules, MTU, encryption, and address allocation remain deployment concerns.

Area	Separate clusters without Cluster Mesh	Cilium Cluster Mesh
Service visibility	Services and endpoints are normally local to a cluster	Selected services can expose eligible endpoints across participating clusters
Traffic path	Cross-cluster access needs a separate gateway, load balancer, or custom path	Cilium can route service traffic to remote cluster endpoints when the network permits it
Workload placement	Each cluster schedules its own workloads	Each cluster still schedules its own workloads; Cluster Mesh is not a global scheduler
Network identity	Remote addresses may be treated as ordinary IP traffic	Cilium can exchange identities used for policy decisions across the mesh
Control plane	Cluster APIs remain separate	Cluster APIs remain separate; only the required Cilium state is exchanged
Operational scope	Teams manage cross-cluster integration themselves	Cilium adds shared connectivity and service mechanisms, plus mesh-specific failure modes to operate

DNS remains one possible naming layer, not the mesh itself. RFC 1035 defines the DNS message format and core domain-name system behavior; it does not specify Kubernetes multi-cluster networking. A successful name lookup cannot prove that a remote endpoint is routable or allowed by policy.

Components and Key Concepts

Cluster name and ID: Each participating Cilium cluster needs a distinct human-readable name and numeric cluster ID. These values help distinguish identities and endpoint state. Choose them before production rollout and keep them unique across every cluster that may join the mesh.

Cluster Mesh control components: Cilium deploys components that expose and exchange the state required for connected clusters. Cilium’s setup workflow uses cilium clustermesh enable in each cluster, then connects the contexts. These components are part of the control path; application packets are still handled by Cilium’s node datapaths.

Global services and MCS API: Cilium supports mechanisms for exporting a service across clusters. With global services, matching service definitions are marked for sharing; with the Multi-Cluster Services API, a ServiceExport signals that a service should be available to other clusters. Check the installed Cilium version and API support rather than assuming these models are interchangeable in every setup.

Identity and policy: Cilium identities are derived from labels and can represent workloads more meaningfully than pod IP addresses. Exchanging relevant identity data allows policy to reason about remote workloads. Operators still need to define and test the policy that permits traffic; connection does not mean every workload should trust every other cluster.

Failure boundaries: Clusters can become disconnected while their local control planes and workloads continue to operate. Remote service endpoints can become unavailable or stale during a partition or control-plane problem. Applications need timeouts, retries, and fallback behavior appropriate to their data and consistency requirements.

Real-World Use Cases

Regional service access: A service can be made reachable from workloads in another region while each region retains its own cluster and deployment process.
Shared platform services: Internal DNS, observability collectors, or carefully selected platform APIs can be exposed across clusters without requiring every client to use a public endpoint.
Workload migration: Teams can move services between clusters in stages and maintain a cross-cluster path during a transition. This still requires deliberate traffic shifting and data consistency planning.
Resilience across failure domains: A service may have endpoints in more than one cluster, but a mesh alone does not provide application failover guarantees. Health, dependency behavior, and regional failure testing remain necessary.

For north-south HTTP routing into a cluster, compare this east-west networking role with the Kubernetes Gateway API explainer. For an application-layer service mesh with additional traffic management and proxy behavior, see the Istio service mesh guide.

Getting Started with Cluster Mesh

Treat the following as a lab workflow, not a production-ready configuration. It assumes Cilium is already installed in two reachable Kubernetes clusters, cluster-a and cluster-b, and that the Cilium CLI and kubectl contexts are configured. Cilium’s Cluster Mesh setup guide documents the full prerequisites and installation options.

First, make sure each cluster has a unique Cilium cluster name and ID. The Cilium installation options include settings such as cluster.name and cluster.id; when installing with the Cilium CLI, a lab command has this shape:

cilium install --set cluster.name=cluster-a --set cluster.id=1 --context cluster-a
cilium install --set cluster.name=cluster-b --set cluster.id=2 --context cluster-b

Do not reinstall Cilium this way if it is already managing production clusters. Review the current Helm values and Cilium documentation for the installed release before changing cluster identity or enabling additional components.

Enable Cluster Mesh in both contexts, then establish the connection from one side. The connection command discovers the destination and establishes the relationship in both directions:

cilium clustermesh enable --context cluster-a
cilium clustermesh enable --context cluster-b
cilium clustermesh connect --context cluster-a --destination-context cluster-b
cilium clustermesh status --context cluster-a --wait

For a global service using the Cilium annotation mechanism, define the matching Kubernetes Service in each cluster and mark it for sharing. This example assumes the checkout pods use the app: checkout label and listen on the named http port:

apiVersion: v1
kind: Service
metadata:
  name: checkout
  namespace: commerce
  annotations:
    service.cilium.io/global: "true"
spec:
  type: ClusterIP
  selector:
    app: checkout
  ports:
    - name: http
      port: 8080
      targetPort: http

Apply the appropriate Service definition to both clusters. Before sending application traffic, inspect the mesh and local Service state:

cilium clustermesh status --context cluster-a
kubectl --context cluster-a get service checkout -n commerce
kubectl --context cluster-b get service checkout -n commerce
kubectl --context cluster-a get endpointslices -n commerce
kubectl --context cluster-b get endpointslices -n commerce

Then test from a client workload in one cluster using the service name and port that your environment exposes. Confirm the request reaches the intended remote endpoint, review Cilium policy and flow visibility, and test what the client observes when the remote cluster is disconnected. If endpoints are missing, check that the service definitions and selectors match, pods are ready, sharing is enabled, and the Cilium agents report a healthy mesh. If endpoints exist but traffic fails, inspect routing, firewall rules, policy, and MTU between nodes.

Common Misconceptions

“Cluster Mesh turns multiple clusters into one Kubernetes cluster.” It does not merge their API servers, scheduling, namespaces, or administrative boundaries. Each cluster continues to be managed independently.

“A shared service means all workloads can call it.” Service discovery and reachability do not replace network policy, application authentication, or authorization. Define the allowed sources and destinations explicitly.

“Cross-cluster service sharing replicates application data.” Cluster Mesh makes networking and selected service endpoints available; it does not replicate databases, synchronize application state, or guarantee a safe failover. Those guarantees belong to the application and its data systems.

“A healthy mesh makes remote traffic reliable.” It establishes mechanisms for connectivity, but underlay failures, partitions, policy mistakes, and unhealthy applications remain possible. Monitor both the mesh control status and end-to-end service behavior.

Changelog

Last updated: October 12. Initial publication.