Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Docs Menu
Docs Home
/ /
Architecture
Docs Home
/
Management
/
Controllers for Kubernetes Operator
/
Architecture
Docs Home
/
Management
/
Controllers for Kubernetes Operator
/
Architecture

MongoDB Database Resource Architecture

The MongoDB custom resource defines database deployments that the Kubernetes Operator manages. Your custom resource specifications define these resources, and the Kubernetes Operator monitors them. When you update a resource's specification, the Kubernetes Operator pushes the changes to Ops Manager, which modifies the MongoDB deployment's configuration.

The MongoDB CRD supports three deployment types. The following diagram illustrates the composition of each:

Diagram showing the high-level architecture of the MongoDB resources in the MongoDB Controllers for Kubernetes Operator
click to enlarge

Warning

Kubernetes Operator doesn't support arbiter nodes.

Standalone Resource

Even though you can deploy a Standalone resource, we recommend that you deploy a ReplicaSet resource with one member instead, because a replica set allows you to add members in the future. In Kubernetes, a Standalone resource is equivalent to a ReplicaSet resource with only one member.

For a Standalone resource, the Kubernetes Operator deploys a replica set with a single member as a StatefulSet. The Kubernetes Operator creates the StatefulSet, which contains the Pod specification, and relies on the Kubernetes StatefulSet Controller to create the Pod for this single mongod instance.

Replica Set Resource

For a ReplicaSet resource, the Kubernetes Operator deploys a replica set as a StatefulSet, with a number of members equal to the value of spec.members. The Kubernetes Operator relies on the Kubernetes StatefulSet Controller to create one Pod per member. Each Pod runs a MongoDB Agent instance that manages the mongod process on that Pod.

Sharded Cluster Resource

A ShardedCluster resource consists of config servers, mongos instances, and shard members. The Kubernetes Operator deploys:

  • One StatefulSet for all config servers

  • One StatefulSet for all mongos instances

  • One StatefulSet for each shard

The Kubernetes Operator relies on the Kubernetes StatefulSet Controller to create one Pod in each StatefulSet. For a sharded cluster with 2 shards, this means 4 StatefulSets total (1 for config servers + 1 for mongos + 2 for shards).

Deployment Type
StatefulSets
Size of StatefulSet

Standalone

1

1 Pod

Replica Set

1

1 Pod per member

Sharded Cluster

<numberOfShards> + 2

1 Pod per mongos, shard member, or config server member

MongoDB Resource Reconciliation

When you apply a MongoDB custom resource specification, the Kubernetes Operator deploys each resource as a StatefulSet. The Kubernetes Operator then enters a continuous reconciliation loop:

  1. Reads project configuration from the ConfigMap specified in spec.opsManager.configMapRef.name.

  2. Reads API credentials from the Secret specified in spec.credentials or from your secret storage tool.

  3. Connects to Ops Manager and performs the following:

    • Reads the organization from the orgId in the ConfigMap.

    • Reads or creates the project specified in projectName.

    • Verifies the <project-id>-group-secret exists, or creates it with Ops Manager API keys.

    • Registers the Kubernetes Operator as a watcher of the ConfigMap and credential Secrets.

  4. Verifies TLS and X.509 certificates, if enabled:

    • For replica sets: looks for certificates in <prefix>-<resource-name>-cert.

    • For sharded clusters: looks for certificates in <prefix>-<resource-name>-x-cert (per shard), <prefix>-<resource-name>-config-cert (config servers), and <prefix>-<resource-name>-mongos-cert (mongos instances).

  5. Creates or updates StatefulSets. The number depends on the deployment type. At this point, each Pod runs a MongoDB Agent but does not yet contain mongod instances.

    • Each MongoDB Agent polls Ops Manager for the automation configuration.

    • On non-static containers, the MongoDB Agent downloads MongoDB binaries with the version specified in spec.version.

    • After receiving the configuration, the MongoDB Agent starts mongod.

    • The Kubernetes Operator generates PersistentVolumeClaims for each Pod (except mongos Pods), unless spec.persistent is false.

  6. Pushes automation configuration updates to Ops Manager. Each MongoDB Agent polls for the updated configuration and applies it. If you change any field, the Kubernetes Operator performs a rolling update of the StatefulSets.

  7. Creates or updates Kubernetes Services:

    • For ReplicaSet or Standalone: a headless ClusterIP service named <resource-name>-svc.

    • For ShardedCluster:

      • mongos: uses the name in spec.service or <resource-name>-svc.

      • Config servers: <resource-name>-cs.

      • Each shard: <resource-name>-sh.

The following diagram illustrates the reconciliation flow for replica sets:

Diagram showing replica set reconciliation flow
click to enlarge

The following diagram illustrates the reconciliation flow for sharded clusters:

Diagram showing sharded cluster reconciliation flow
click to enlarge

MongoDBUser Resource Reconciliation

If the user authentication method is SCRAM, the MongoDBUser resource depends on a secret that stores user credentials. The Kubernetes Operator watches the Secret for changes and reconciles as follows:

  1. Determines the MongoDB user's resource from spec.MongoDBResourceRef.name.

  2. Connects to Ops Manager, reads the organization and project, and verifies the agent secret.

  3. Updates the user's credentials in Ops Manager or creates a new user if it doesn't exist. If the username has changed, the Kubernetes Operator removes the old name and adds a new one.

The following diagram illustrates the MongoDBUser reconciliation flow:

Diagram showing MongoDBUser reconciliation flow
click to enlarge

Back

Architecture

Next

Ops Manager Custom Resource Architecture

On this page