Configure the MongoDB Custom Resource

Choosing a Deployment Type

The very first decision you need to make is which type of MongoDB deployment to create. The spec.type field accepts three values, each targeting a different set of workloads and operational requirements. Understanding the trade-offs between them is essential before you write a single line of YAML.

Standalone instances run a single mongod process. They are best suited for local development, testing scenarios, or evaluating features where redundancy is not a concern. Because a standalone deployment has no replication, it does not support automatic failover and is not recommended for production data.

Replica Sets are the default production topology for MongoDB. A replica set consists of multiple mongod members (typically three or more) that maintain identical copies of your data. If the primary member fails, the surviving members elect a new primary without manual intervention. Choosing a replica set gives you high availability, read scalability through secondary reads, and the ability to perform rolling maintenance. For most teams, this is where you start:

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: my-replica-set
spec:
  type: ReplicaSet
  members: 3
  version: "8.0.0"
  opsManager:
    configMapRef:
      name: my-project-configmap
  credentials: my-credentials
  persistent: true

Sharded Clusters distribute data across multiple shards, each of which is itself a replica set. In front of the shards sit mongos routers that direct client traffic, and a dedicated config server replica set that stores cluster metadata. If your dataset is growing beyond what a single replica set can efficiently serve, or you need to scale writes horizontally, a sharded cluster is the right choice. The configuration is more involved because you must specify counts for shards, mongod instances per shard, mongos routers, and config servers:

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: my-sharded-cluster
spec:
  type: ShardedCluster
  shardCount: 2
  mongodsPerShardCount: 3
  mongosCount: 2
  configServerCount: 3
  version: "8.0.0"
  opsManager:
    configMapRef:
      name: my-project-configmap
  credentials: my-credentials
  persistent: true

For full details on every field specific to each deployment type, see the Standalone, Replica Set, and Sharded Cluster sections of the specification reference.

Connecting to Ops Manager

Every MongoDB custom resource must be linked to an Ops Manager project. This connection is how the Kubernetes Operator registers your deployment for monitoring, automation, and backup. Two pieces of configuration make the connection work: a ConfigMap that identifies your project, and a Secret that stores your API credentials.

The ConfigMap tells the Kubernetes Operator which Ops Manager project to place the deployment in. At a minimum it must contain a projectName and a baseUrl that points to your Ops Manager instance. Optionally, you can pin the deployment to a specific organization with orgId:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-project-configmap
data:
  projectName: "MyKubernetesProject"
  baseUrl: "https://ops-manager.example.com"
  orgId: "5e8f8b8b8b8b8b8b8b8b8b8b"

The Secret holds the programmatic API key pair that the Kubernetes Operator uses to authenticate to the Ops Manager API on your behalf:

kubectl create secret generic my-credentials \
  --from-literal="publicKey=<public-api-key>" \
  --from-literal="privateKey=<private-api-key>"

You then reference both in your MongoDB CR:

spec:
  opsManager:
    configMapRef:
      name: my-project-configmap
  credentials: my-credentials

To learn more about creating these prerequisites, see Create Credentials for the Kubernetes Operator and Create One Project Per MongoDB Deployment Using a ConfigMap.

MongoDB Version and Feature Compatibility

The spec.version field sets the MongoDB server version that the Kubernetes Operator deploys (for example, "8.0.0"). Choosing the right version is not just about getting the latest features. You should also consider the version compatibility matrix with your driver libraries, the Ops Manager version you are running, and your team's upgrade cadence.

When upgrading between major versions, the featureCompatibilityVersion (FCV) field gives you a safety net. FCV controls which storage-engine and replication features are active, and it can be set lower than the binary version itself. This lets you upgrade the binaries first, verify stability, and then raise the FCV to unlock new features in a separate, deliberate step. If you need to roll back, a lower FCV ensures the data files remain compatible with the previous binary version.

spec:
  version: "8.0.0"
  featureCompatibilityVersion: "7.0"

For reference, see spec.version and spec.featureCompatibilityVersion in the specification.

Securing Your Deployment

Security on a MongoDB deployment in Kubernetes has two dimensions: encrypting network traffic with TLS and authenticating clients and cluster members. Both are configured under the spec.security block, and understanding how they interact is critical to getting a deployment that is both secure and functional.

spec:
  security:
    certsSecretPrefix: "mdb"
    tls:
      enabled: true
      ca: "custom-ca-configmap"

spec:
  security:
    tls:
      enabled: true
    authentication:
      enabled: true
      modes: ["SCRAM", "X509"]
      internalCluster: "X509"

Storage and Persistence

MongoDB is a stateful workload, and how you configure storage directly impacts performance, durability, and your ability to recover from failures. The spec.persistent field must be set to true for any environment where data loss is unacceptable (which is essentially every environment beyond throwaway tests). When persistence is enabled, the Kubernetes Operator creates PersistentVolumeClaims (PVCs) that survive Pod restarts and rescheduling.

spec:
  podSpec:
    persistence:
      multiple:
        data:
          storage: "200Gi"
          storageClass: "fast-ssd"
        journal:
          storage: "50Gi"
          storageClass: "fast-ssd"
        logs:
          storage: "20Gi"
          storageClass: "standard"

spec:
  podSpec:
    persistence:
      single:
        storage: "100Gi"
        storageClass: "standard"

Resource Allocation and Pod Templates

Right-sizing CPU and memory for MongoDB Pods is one of the most impactful decisions you make at deployment time, and one you will likely revisit as workloads evolve. The Kubernetes Operator exposes resource controls through the podSpec (for replica sets and standalones) and through shardPodSpec, configSrvPodSpec, and mongosPodSpec (for sharded clusters).

Setting both requests and limits for CPU and memory ensures that Kubernetes schedules your Pods onto nodes with adequate capacity and prevents runaway processes from affecting other workloads on the same node. The following example illustrates a configuration that you can use as a starting point. In this configuration, you create production replica set members with at least 2 CPU cores and 4 GiB of memory as requests, with limits set to match or exceed those values:

spec:
  podSpec:
    podTemplate:
      spec:
        containers:
          - name: mongodb-enterprise-database
            resources:
              requests:
                cpu: "2"
                memory: "4Gi"
              limits:
                cpu: "4"
                memory: "8Gi"

Pod templates also allow you to set labels, annotations, tolerations, and affinity rules. Affinity rules are particularly important in production, because they control how replica set members are distributed across Kubernetes nodes and failure domains.

For example, the following affinity rule spreads members across availability zones to protect against zone-level outages:

spec:
  podSpec:
    podTemplate:
      spec:
        affinity:
          podAntiAffinity:
            requiredDuringSchedulingIgnoredDuringExecution:
              - labelSelector:
                  matchLabels:
                    app.kubernetes.io/name: my-replica-set
                topologyKey: "topology.kubernetes.io/zone"

For a complete list of podTemplate fields, see the specification reference, particularly spec.podSpec.podTemplate.spec.affinity.

Configuring Backups

Backups in Kubernetes Operator use the continuous backup capability built into Ops Manager. When enabled, Ops Manager captures the oplog in real time and takes periodic snapshots, which together give you point-in-time recovery. This means you can restore to any second within your configured retention window, not just to the timestamp of the last snapshot.

To enable backup on a MongoDB resource, set spec.backup.mode to enabled. You can also configure a snapshot schedule that controls how frequently snapshots are taken and how long they are retained, as shown in the following example:

spec:
  backup:
    mode: enabled
    snapshotSchedule:
      snapshotIntervalHours: 6
      snapshotRetentionDays: 7
      dailySnapshotRetentionDays: 30
      pointInTimeWindowHours: 24

If your organization requires encryption of backup data at rest, you can integrate with a KMIP-compliant key management server, as shown in the following example:

spec:
  backup:
    mode: enabled
    encryption:
      kmip:
        client:
          clientCertificatePrefix: "backup-kmip"

The autoTerminateOnDeletion flag controls whether backup data is cleaned up when the MongoDB resource is deleted. Set it to true in non-production environments to avoid orphaned backup state; leave it false in production so that backup data survives accidental resource deletion:

spec:
  backup:
    mode: enabled
    autoTerminateOnDeletion: false

Assignment labels let you control which backup infrastructure (oplog stores, snapshot stores) a particular deployment uses, which is useful when multiple deployments share a single Ops Manager instance.

For the full set of backup settings, see the Replica Set Settings in the specification reference. To learn how to deploy the backup infrastructure itself, see Configure MongoDB Database Backups.

Exposing Your Deployment Externally

By default, MongoDB deployments in Kubernetes are reachable only within the cluster. Many teams need to access their databases from applications running outside Kubernetes, from client tools during development, or from a different Kubernetes cluster in a multi-region architecture.

The spec.externalAccess block instructs the Kubernetes Operator to create Kubernetes Services that route external traffic to your MongoDB Pods. You can choose between LoadBalancer services, which provision cloud-provider load balancers, and NodePort services, which expose static ports on every cluster node, as shown in the following example:

spec:
  externalAccess:
    externalService:
      spec:
        type: LoadBalancer
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"

For replica sets, you can additionally configure externalDomain to assign predictable DNS hostnames to each member, which simplifies connection string construction on the client side:

spec:
  externalAccess:
    externalDomain: "mongodb.example.com"
    externalService:
      spec:
        type: LoadBalancer

To learn more, see Connect to a MongoDB Database Resource from Outside Kubernetes.

Tuning MongoDB Server Parameters

Not every MongoDB tuning setting has a first-class field in the custom resource. For any settings that are not included in the Kubernetes Operator's explicit schema, the spec.additionalMongodConfig block lets you pass arbitrary mongod configuration options. These are translated directly into the server configuration that Ops Manager applies.

Common uses for additionalMongodConfig include adjusting the WiredTiger cache size, restricting TLS protocol versions, or changing the listening port, as shown in the following example:

spec:
  additionalMongodConfig:
    net:
      tls:
        disabledProtocols: "TLS1_0,TLS1_1"
    storage:
      wiredTiger:
        engineConfig:
          cacheSizeGB: 4

In a sharded cluster, each component (shard, config server, mongos) has its own additionalMongodConfig field, so you can tune them independently. For the full list of supported options, see MongoDB Server Parameters in the MongoDB Manual.

MongoDB Agent Configuration

Each MongoDB Pod runs a MongoDB Agent that manages the mongod process, handles automation tasks, and reports health to Ops Manager. You can tune MongoDB Agent behavior through spec.agent, including startup options like log rotation limits and connection timeouts, as shown in the following example:

spec:
  agent:
    startupOptions:
      maxLogFiles: "10"
      maxLogFileSize: "100"
      dialTimeout: "20"

The spec.logLevel field sets the MongoDB Agent's log verbosity. During initial setup or troubleshooting, DEBUG can be invaluable; in steady-state production, INFO or WARN avoids excessive log volume:

spec:
  logLevel: "DEBUG"

For complete MongoDB Agent-related settings, see the specification reference.

Multi-Cluster Deployments

For teams that need to distribute a single MongoDB deployment across multiple Kubernetes clusters, perhaps for geographic redundancy, disaster recovery, or data sovereignty, the Kubernetes Operator supports a multi-cluster topology. Setting spec.topology to MultiCluster instructs the Kubernetes Operator that the replica set members defined in spec.clusterSpecList live in different Kubernetes clusters, as shown in the following example:

spec:
  topology: MultiCluster
  clusterSpecList:
    - clusterName: "cluster-us-east"
      members: 2
    - clusterName: "cluster-us-west"
      members: 2
    - clusterName: "cluster-eu-west"
      members: 1

Multi-cluster deployments introduce additional prerequisites, including cross-cluster networking and service mesh or external DNS configuration. Before proceeding, review the multi-cluster prerequisites and multi-cluster architecture.

For the multi-cluster specification fields, see the Multi-Kubernetes-Cluster Specification.

Maintaining Your MongoDB Custom Resource Configuration Over Time

A MongoDB custom resource is not a one-time artifact. As your team's requirements evolve, you will scale members, add shards, enable backup, rotate TLS certificates, upgrade MongoDB versions, or adjust resource limits. The Kubernetes Operator is designed for this: you update the YAML manifest, apply it with kubectl apply, and the Kubernetes Operator reconciles the changes incrementally.

A few guidelines for safe iteration:

• Scale members gradually. Adding or removing replica set members one at a time reduces the risk of election disruption.

• Upgrade versions in two steps. Bump the binary version first while holding featureCompatibilityVersion at the previous level, then raise FCV after verifying stability.

• Rotate certificates before expiry. TLS certificates have a finite lifetime. Plan a rotation process, ideally automated with cert-manager, and test it in a non-production environment first.

• Test storage changes carefully. Some storage changes (like switching storage classes) may require manual volume migration. Always validate in a staging cluster.

• Monitor the resource status. After any change, validate that the Kubernetes Operator reconciled your changes successfully by checking the resource status with kubectl get mdb and reviewing the Kubernetes Operator logs for reconciliation errors.

For hands-on procedures for modifying a deployment, see Edit a Database Resource.

Putting It All Together

The following example combines the concepts covered on this page into a production-ready replica set configuration. It includes TLS, SCRAM authentication, backup, anti-affinity scheduling, split data/journal/log volumes, and WiredTiger tuning:

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: prod-replica-set
  namespace: mongodb-production
spec:
  type: ReplicaSet
  members: 3
  version: "8.0.0"
  featureCompatibilityVersion: "8.0"
  opsManager:
    configMapRef:
      name: prod-project-configmap
  credentials: prod-credentials
  persistent: true
  security:
    certsSecretPrefix: "prod-mdb"
    tls:
      enabled: true
      ca: "prod-ca-configmap"
    authentication:
      enabled: true
      modes: ["SCRAM"]
      internalCluster: "X509"
  backup:
    mode: enabled
    autoTerminateOnDeletion: false
    snapshotSchedule:
      snapshotIntervalHours: 6
      snapshotRetentionDays: 7
      dailySnapshotRetentionDays: 30
      pointInTimeWindowHours: 48
  podSpec:
    persistence:
      multiple:
        data:
          storage: "500Gi"
          storageClass: "fast-ssd"
        journal:
          storage: "100Gi"
          storageClass: "fast-ssd"
        logs:
          storage: "50Gi"
          storageClass: "standard"
    podTemplate:
      spec:
        containers:
          - name: mongodb-enterprise-database
            resources:
              requests:
                cpu: "2"
                memory: "8Gi"
              limits:
                cpu: "4"
                memory: "16Gi"
        affinity:
          podAntiAffinity:
            requiredDuringSchedulingIgnoredDuringExecution:
              - labelSelector:
                  matchLabels:
                    app.kubernetes.io/name: prod-replica-set
                topologyKey: "topology.kubernetes.io/zone"
  additionalMongodConfig:
    net:
      tls:
        disabledProtocols: "TLS1_0,TLS1_1"
    storage:
      wiredTiger:
        engineConfig:
          cacheSizeGB: 8