MongoDB Architecture in KubeBlocks

KubeBlocks supports two distinct MongoDB deployment architectures:

Replica Set Architecture

A MongoDB replica set maintains multiple copies of the same dataset across pods. One pod acts as the primary (accepts all writes); the others are secondaries that replicate the primary's oplog and can serve reads.

Resource Hierarchy

Cluster  →  Component  →  InstanceSet  →  Pod × N

Containers Inside Each Pod

Each replica set pod runs three containers (plus three init containers on startup: init-syncer copies /bin/syncer and /bin/syncerctl to /tools; init-kubectl copies the kubectl binary to dataMountPath/tmp/bin; init-pbm-agent copies pbm, pbm-agent, and pbm-agent-entrypoint to /tools):

Each pod mounts its own PVC for the MongoDB data directory (default /data/mongodb, set by dataMountPath in chart values).

High Availability

MongoDB replica sets use oplog-based replication and a majority-vote (Raft-like) election protocol:

A 3-member replica set tolerates 1 failure.

Automatic Failover

1. Primary pod crashes or becomes unreachable — secondaries stop receiving heartbeat pings
2. Election timeout — after approximately 10 seconds (electionTimeoutMillis), one secondary calls for an election
3. Majority vote — the candidate with the most up-to-date oplog and a majority of votes wins and becomes the new primary
4. KubeBlocks roleProbe detects the change — syncerctl getrole returns primary for the new pod → kubeblocks.io/role=primary label is applied
5. Service endpoints switch — the {cluster}-mongodb-mongodb ClusterIP service automatically routes writes to the new primary

Failover typically completes within 10–30 seconds.

Traffic Routing

• Write traffic: connect to {cluster}-mongodb-mongodb:27017 (roleSelector: primary — always routes to the current primary)
• Read-only traffic: connect to {cluster}-mongodb-mongodb-ro:27017 (roleSelector: secondary)
• {cluster}-mongodb (two-segment name) is the everypod service — it routes to all pods and is not a write-only endpoint

Sharding Architecture

MongoDB Sharding distributes data across multiple independent replica sets (shards) using a shard key. A layer of stateless mongos routers sits in front, and a config server replica set (CSRS) stores the chunk routing metadata.

Resource Hierarchy

The sharding topology uses both Component (for mongos and config-server) and Sharding (for data shards):

Cluster  →  Component (mongos)         →  InstanceSet  →  Pod × N
         →  Component (config-server)  →  InstanceSet  →  Pod × 3
         →  Sharding  (shard)          →  Shard × N    →  InstanceSet  →  Pod × replicas

Component Details

Mongos pods (stateless — no PVC; each pod also runs an init-kubectl init container that copies the kubectl binary into the container's tools path for use by lifecycle scripts):

Config server pods (3-node CSRS replica set; same three init containers as replica set pods — init-syncer, init-kubectl, init-pbm-agent):

Shard pods (each shard = independent replica set; same three init containers — init-syncer, init-kubectl, init-pbm-agent):

Each shard pod mounts its own PVC for its data directory. At least 3 shards are recommended for balanced distribution (not enforced by the addon).

How Query Routing Works

1. Client connects to any mongos on port 27017 — no cluster-aware driver required
2. Mongos reads the chunk map from the CSRS to determine which shard owns the target key range
3. Mongos forwards the query to the primary of the target shard
4. For scatter-gather queries (no shard key filter), mongos fans out to all shard primaries and merges results
5. On chunk migrations or shard additions, mongos automatically discovers the updated routing table

Traffic Routing

Clients connect through mongos using a MongoDB URI seed list, e.g.:

mongodb://{cluster}-mongos-mongos-0:27017,{cluster}-mongos-mongos-1:27017/

Or use {cluster}-mongos-headless for DNS-based discovery. Direct shard or config server access is not intended for application traffic.

Automatic Failover

Each component fails over independently:

• Shard primary fails → that shard's replica set elects a new primary (≈10 s); mongos retries on the new primary automatically
• Config server primary fails → CSRS elects a new primary; chunk map reads resume; mongos does not lose routing data (it caches the chunk map locally)
• Mongos pod fails → clients reconnect to another mongos pod; mongos is stateless so no data is lost

System Accounts

KubeBlocks automatically manages the following MongoDB system accounts. Passwords are stored in Secrets named {cluster}-{component}-account-{name}.