kubernetesmulti clusterPractitioner

Mastering Multi-Cluster Databases on Kubernetes: Architecture and Deployment

5 min read CNCF BlogJul 22, 2026Reviewed for accuracy

Practitioner — Hands-on experience recommended

In today's cloud-native world, managing databases across multiple Kubernetes clusters is crucial for ensuring high availability and resilience. Multi-cluster databases solve the problem of single points of failure by distributing your database nodes across different clusters, allowing for seamless failover and load balancing. This architecture is particularly beneficial for applications that require constant uptime and rapid scaling.

The architecture divides clusters into two roles: the Main Site and the Replica Site. The Main Site is fully managed by the Operator and holds the Primary node, handling application writes. The Replica Site operates in unmanaged mode, meaning it does not generate certificates or user credentials and does not attempt to initialize a new replica set. This setup allows all nodes, regardless of their cluster, to belong to a single MongoDB replica set, enabling cross-cluster voting and leader elections. To enable this functionality, set the multiCluster.enabled parameter to true and define the DNSSuffix for global DNS resolution.

In production, you need to ensure cross-cluster network connectivity using solutions like Cilium ClusterMesh or Submariner. Be aware that the MCS API isn't included in standard Kubernetes installations, so you’ll need to implement it separately. Additionally, keep in mind that version compatibility is crucial; the current configuration version is crVersion: 1.23.0. Misconfigurations can lead to split-brain scenarios, so always set the unmanaged parameter to true for Replica Sites to prevent this issue.

Key takeaways

→Enable multi-cluster service discovery by setting `multiCluster.enabled` to true.
→Use the MCS API to facilitate MongoDB replica sets across independent Kubernetes clusters.
→Configure the `DNSSuffix` for global DNS resolution to ensure connectivity.
→Set the `unmanaged` parameter to true on Replica Sites to avoid split-brain scenarios.
→Establish cross-cluster network connectivity using Cilium ClusterMesh or Submariner.

Why it matters

Implementing multi-cluster databases can drastically reduce downtime and improve application resilience, making it essential for mission-critical applications that demand high availability.

Code examples

YAML

1apiVersion: psmdb.percona.com/v1
2kind: PerconaServerMongoDB
3metadata:
4  name: main-cluster
5spec:
6  crVersion: 1.23.0
7  image: perconalab/percona-server-mongodb-operator:main-mongod8.0
8  imagePullPolicy: Always
9  updateStrategy: SmartUpdate
10    multiCluster:
11      enabled: true  # <---  Enable multi-cluster service discovery
12      DNSSuffix: svc.clusterset.local  # <--- The Global DNS standard

YAML

1apiVersion: psmdb.percona.com/v1
2kind: PerconaServerMongoDB
3metadata:
4  name: replica-cluster
5spec:
6  unmanaged: true
7  multiCluster:
8    enabled: true
9    DNSSuffix: svc.clusterset.local

YAML

1replsets:
2- name: rs0
3  size: 2
4  externalNodes:
5  - host: main-cluster-rs0-0.psmdb.svc.clusterset.local
6    votes: 1
7    priority: 1
8  - host: main-cluster-rs0-1.psmdb.svc.clusterset.local
9    votes: 0
10    priority: 0