MongoDB Kubernetes Operator: Deploy Replica Sets (2026)

Kubernetes can manage MongoDB replica sets, but it’s not just about telling it to run a few pods.

Let’s see a replica set in action.

apiVersion: mongodbcommunity.mongodb.org/v1
kind: MongoDB
metadata:
  name: my-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "5.0.10"
  users:
    - name: root
      db: admin
      passwordSecret:
        name: mongodb-root-password
        key: password
      roles:
        - name: root
          db: admin
  security:
    authentication:
      authorization: enabled

This MongoDB custom resource is the blueprint. The MongoDB Operator watches for these resources and translates them into actual MongoDB deployments.

Here’s the mental model:

1. The MongoDB Custom Resource (CR): This is your declarative wish. You tell the operator what you want – a replica set named my-mongodb, with 3 members, running version 5.0.10, and a root user.
2. The MongoDB Operator: This is the active agent. It’s a Kubernetes controller that continuously watches the Kubernetes API for MongoDB CRs. When it sees one, it takes action.
3. Kubernetes Resources: The operator doesn’t deploy MongoDB directly. It creates standard Kubernetes resources that MongoDB needs:
   • StatefulSets: These are crucial for stateful applications like databases. They provide stable network identities (e.g., my-mongodb-0.my-mongodb-headless.default.svc.cluster.local) and persistent storage for each replica.
   • Pods: The StatefulSet creates pods, which are the actual containers running the MongoDB mongod process.
   • Services: A headless service is created for the StatefulSet, enabling DNS resolution for individual members. A regular ClusterIP service is often created to provide a stable entry point to the replica set.
   • Secrets: The passwordSecret you define is used to create or reference a Kubernetes Secret containing the MongoDB root password.
   • Persistent Volume Claims (PVCs): Each pod gets its own PVC to ensure its data persists across pod restarts or rescheduling.

When you apply the MongoDB CR, the operator does the following:

• Creates a StatefulSet: It defines the desired number of pods (members: 3). Each pod will have a stable identity.
• Configures mongod: It generates a mongod.conf.yaml for each member, ensuring they are configured as part of a replica set named my-mongodb. This includes setting replication.replSetName: "my-mongodb".
• Manages Pods: The StatefulSet ensures that the correct number of pods are running, that they have unique and stable network identifiers, and that their storage is managed.
• Initializes the Replica Set: The operator is smart enough to figure out which member is the primary and initiates the replica set. It uses the rs.initiate() command internally, typically from one of the pods, targeting the other members via their stable DNS names.
• Applies Security: It creates the specified user with the provided credentials from the referenced secret.

The stable network identity provided by StatefulSets is key here. For example, the pods might be named my-mongodb-0, my-mongodb-1, and my-mongodb-2. The headless service allows them to resolve each other using names like my-mongodb-0.my-mongodb-headless.default.svc.cluster.local. The operator uses these stable names to configure the replica set members to discover and communicate with each other.

The version field is not just for the Docker image; it also influences the configuration options the operator uses when bootstrapping the replica set and setting up mongod.conf.yaml. Different MongoDB versions have slightly different configuration syntax or default behaviors.

Crucially, the operator handles the complex task of replica set initialization. Without it, you’d have to manually SSH into one pod, get the connection strings for the others, and run rs.initiate() yourself. The operator automates this, ensuring that the replica set is properly formed and that a primary is elected.

The users and security.authentication sections are where you define access control. The operator ensures that MongoDB starts with authentication enabled and creates the specified users and roles. The passwordSecret is a standard Kubernetes mechanism for securely storing sensitive information.

When you update the MongoDB CR, for instance, changing the members count, the operator will again reconcile the state. If you increase members, it will add new pods via the StatefulSet and then prompt the existing replica set to add these new members. If you decrease members, it will gracefully step down any primaries on the nodes to be removed, remove the member from the replica set configuration, and then scale down the StatefulSet.

The most surprising thing is that the operator doesn’t just deploy MongoDB pods; it actively participates in the MongoDB replica set’s lifecycle, from initialization to reconfigurations, using its understanding of both Kubernetes and MongoDB’s internal APIs.

Once your replica set is running and stable, you’ll likely want to configure application access to it, which involves setting up appropriate connection strings and potentially a load balancer service.