Kubeblocks Addon Mongodb

Deploy MongoDB on KubeBlocks

Overview

Deploy MongoDB clusters on Kubernetes using KubeBlocks. Supports ReplicaSet for HA and Sharding for horizontal scaling with mongos routers and config servers.

Official docs: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-mongodb/cluster-management/create-and-connect-a-mongodb-cluster Full doc index: https://kubeblocks.io/llms-full.txt

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed (see install-kubeblocks)
• The MongoDB addon must be enabled:

# Check if mongodb addon is installed
helm list -n kb-system | grep mongodb

# Install if missing
helm install kb-addon-mongodb kubeblocks/mongodb --namespace kb-system --version 1.0.0

Available Topologies

Supported Versions

MongoDB 4.0 through 7.0 are supported. Common serviceVersion values:

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster (choose topology)
- [ ] Step 4: Wait for cluster to be ready
- [ ] Step 5: Connect to MongoDB

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep mongodb

If not found:

helm install kb-addon-mongodb kubeblocks/mongodb --namespace kb-system --version 1.0.0

Step 2: Create Namespace

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -

Step 3: Create Cluster

ReplicaSet (Recommended)

Standard HA setup with automatic primary election:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mongo-cluster
  namespace: demo
spec:
  clusterDef: mongodb
  topology: replicaset
  terminationPolicy: Delete
  componentSpecs:
    - name: mongodb
      serviceVersion: "7.0.12"
      replicas: 3
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Apply:

kubectl apply -f mongo-cluster.yaml

Key points:

• 3 replicas is the minimum for a proper ReplicaSet (allows majority voting)
• MongoDB automatically elects a primary among the replicas

Sharding

For horizontal scaling across multiple shards. Uses both spec.shardings (for shard data) and spec.componentSpecs (for config-server and mongos):

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: mongo-sharded
  namespace: demo
spec:
  clusterDef: mongodb
  topology: sharding
  terminationPolicy: Delete
  shardings:
    - name: shard
      shards: 2
      template:
        name: mongodb
        serviceVersion: "7.0.12"
        replicas: 3
        resources:
          limits: {cpu: "0.5", memory: "0.5Gi"}
          requests: {cpu: "0.5", memory: "0.5Gi"}
        volumeClaimTemplates:
          - name: data
            spec:
              accessModes: [ReadWriteOnce]
              resources: {requests: {storage: 20Gi}}
  componentSpecs:
    - name: config-server
      serviceVersion: "7.0.12"
      replicas: 3
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}
    - name: mongos
      serviceVersion: "7.0.12"
      replicas: 2
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}

Key points:

• Shards use spec.shardings (each shard is a ReplicaSet)
• Config-server and mongos use spec.componentSpecs
• shards: 2 creates 2 shards (each with 3 replicas)
• Connect to mongos for data operations (port 27017)
• Config-server stores sharding metadata

Step 4: Wait for Cluster Ready

kubectl -n demo get cluster <cluster-name> -w

Wait until STATUS shows Running. Sharded clusters take longer (3-5 minutes).

Check pods:

kubectl -n demo get pods -l app.kubernetes.io/instance=<cluster-name>

Step 5: Connect to MongoDB

Get Credentials

# Secret name format: <cluster>-mongodb-account-root
kubectl -n demo get secret mongo-cluster-mongodb-account-root -o jsonpath='{.data.password}' | base64 -d

Connect via kubectl exec

# ReplicaSet
kubectl -n demo exec -it mongo-cluster-mongodb-0 -- mongosh --username root --authenticationDatabase admin

# Sharded cluster (connect via mongos)
kubectl -n demo exec -it mongo-sharded-mongos-0 -- mongosh --username root --authenticationDatabase admin

Connect via Port-Forward

# ReplicaSet
kubectl -n demo port-forward svc/mongo-cluster-mongodb 27017:27017

# Sharded (via mongos)
kubectl -n demo port-forward svc/mongo-sharded-mongos 27017:27017

# Then from another terminal:
mongosh mongodb://root:<password>@127.0.0.1:27017/admin

Troubleshooting

Cluster stuck in Creating:

kubectl -n demo describe cluster <cluster-name>
kubectl -n demo get events --sort-by='.lastTimestamp'

ReplicaSet not forming:

kubectl -n demo exec -it mongo-cluster-mongodb-0 -- mongosh --eval "rs.status()"

Sharding status:

kubectl -n demo exec -it mongo-sharded-mongos-0 -- mongosh --eval "sh.status()"

Day-2 Operations

Safety Patterns

Follow safety-patterns.md for dry-run before apply, status confirmation after watch, and pre-deletion checklist.

Next Steps

• For detailed sharding YAML examples, see reference.md