/ /

Deploy Ops Manager

Docs Home

Management

Controllers for Kubernetes Operator

Deploy Ops Manager

Docs Home

Management

Controllers for Kubernetes Operator

Deploy Ops Manager

Configure the Ops Manager Custom Resource

Ops Manager is the self-hosted control plane for MongoDB Enterprise deployments. When you run it on Kubernetes, you define it as a MongoDBOpsManager custom resource, and the Kubernetes Operator handles the lifecycle of the Ops Manager application servers, the backing Application Database, and, optionally, the entire backup infrastructure. Getting the configuration of this resource right is foundational: every MongoDB database resource you deploy later depends on a healthy, well-connected Ops Manager instance.

This guide takes you through the design decisions and conceptual areas of the Ops Manager custom resource, explaining what each block controls, when you need it, and how the pieces fit together. The goal is to prepare you to write a manifest that reflects your organization's requirements from day one, and to give you a mental model for iterating on that manifest as those requirements change.

For the complete field-by-field specification, see the Ops Manager Resource Specification.

Admin Credentials and Initial Setup

Before the Ops Manager application can start, it needs an initial administrator account. You provide these credentials through a Kubernetes Secret referenced by spec.adminCredentials. The Secret must contain four keys: Username (an email address), Password, FirstName, and LastName. The Kubernetes Operator uses this information to bootstrap the first Global Owner account when the Ops Manager pod initializes for the first time:

kubectl create secret generic ops-manager-admin-secret \
  --from-literal=Username="admin@example.com" \
  --from-literal=Password="<secure-password>" \
  --from-literal=FirstName="Admin" \
  --from-literal=LastName="User"

Once Ops Manager is running, you can create additional users and API keys through the Ops Manager UI or API. The initial admin secret is only used during first-time setup, but the Kubernetes Operator does reference it for reconciliation, so it should remain in the cluster.

The spec.version field determines which Ops Manager release the Kubernetes Operator deploys. Pin this to a specific X.Y.Z version rather than letting it float. When you are ready to upgrade, update this field and let the Kubernetes Operator perform a rolling upgrade, as shown in the following example:

apiVersion: mongodb.com/v1
kind: MongoDBOpsManager
metadata:
  name: ops-manager
spec:
  replicas: 1
  version: "8.0.0"
  adminCredentials: ops-manager-admin-secret

For details on every required field, see the required settings in the specification reference.

Sizing and Topology for the Ops Manager Resource

The spec.replicas field controls how many Ops Manager application instances run in parallel behind a shared service. A single replica is sufficient for development and evaluation, but production environments should run at least two replicas behind a load balancer to survive Pod restarts and node failures without downtime. There is no functional difference between the replicas; they are all stateless application servers backed by the same Application Database.

For organizations that need geographic redundancy or cross-region high availability, the Kubernetes Operator supports a MultiCluster topology for Ops Manager itself. In this mode, set spec.topology: MultiCluster and define a clusterSpecList that distributes Ops Manager instances across named Kubernetes clusters, as shown in the following example:

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

When you use MultiCluster topology, the spec.replicas field is ignored; member counts are drawn from the clusterSpecList instead. Multi-cluster Ops Manager deployments introduce cross-cluster networking requirements, so review Deploy Ops Manager Resources on Multiple Kubernetes Clusters before adopting this model.

Important

Once an Ops Manager resource is created with SingleCluster topology, it cannot be converted to MultiCluster in place. Plan your topology before the initial deployment.

Application Configuration Properties

Ops Manager has an extensive set of server-side configuration properties, ranging from email settings to feature flags to binary download sources. Rather than translating each of these into a first-class CRD field, the Kubernetes Operator provides the spec.configuration block as a pass-through: you set key-value pairs that map directly to Ops Manager system properties.

The most common properties to set at deployment time are email configuration, so that Ops Manager can send alerts and invitations, and security defaults, as shown in the following example:

spec:
  configuration:
    mms.fromEmailAddr: "ops-manager@example.com"
    mms.replyToEmailAddr: "ops-manager@example.com"
    mms.adminEmailAddr: "admin@example.com"
    mms.mail.hostname: "smtp.example.com"
    mms.mail.port: "587"
    mms.mail.ssl: "true"
    mms.mail.transport: "smtp"
    mms.ignoreInitialUiSetup: "true"

Setting mms.ignoreInitialUiSetup to "true" skips the interactive setup wizard on first launch, which is essential for fully automated deployments.

Other useful properties include the following:

mms.security.allowCORS — controls whether the UI accepts cross-origin requests.
automation.versions.source — set to "remote" (default), "local", or "hybrid" to control how MongoDB binaries are downloaded. See Local and Remote Mode below.
mms.featureFlag.automation.verifyDownloads — when set to "enabled", the agent requires cryptographic signatures for all MongoDB binaries.

For the full catalog of properties, see Ops Manager Configuration Settings and spec.configuration in the specification reference.

Securing Connections with TLS

Running Ops Manager over HTTPS is strongly recommended for any environment beyond local development. Without it, admin credentials, API keys, and monitoring data traverse the network in clear text.

Enabling HTTPS requires the following:

A TLS certificate for the Ops Manager application itself.
A TLS certificate for the Application Database.

Each certificate is stored in a secret whose name follows the pattern <certsSecretPrefix>-<metadata.name>-cert (for the application) or <certsSecretPrefix>-<metadata.name>-db-cert (for the Application Database).

The certsSecretPrefix is how the Kubernetes Operator ties these naming conventions together. If you set spec.security.certsSecretPrefix to "om-prod" and your resource is named ops-manager, the Kubernetes Operator expects secrets named om-prod-ops-manager-cert and (for the Application Database) appdb-prod-ops-manager-db-cert, as shown in the following example:

# Create the Ops Manager TLS certificate secret
kubectl create secret tls om-prod-ops-manager-cert \
  --cert=om-tls.crt \
  --key=om-tls.key
# Create the Application Database TLS certificate secret
kubectl create secret tls appdb-prod-ops-manager-db-cert \
  --cert=appdb-tls.crt \
  --key=appdb-tls.key

If your certificates are signed by a custom Certificate Authority, you must also create ConfigMaps containing the CA certificates. The Ops Manager CA certificate must be named mms-ca.crt inside the ConfigMap. Additionally, this CA file must include the certificate chain for downloads.mongodb.com so that the Backup Daemon can download MongoDB binaries:

spec:
  security:
    certsSecretPrefix: "om-prod"
    tls:
      ca: "om-ca-configmap"
  applicationDatabase:
    security:
      certsSecretPrefix: "appdb-prod"
      tls:
        ca: "appdb-ca-configmap"

For step-by-step HTTPS deployment procedures, including the openssl commands to assemble the CA chain, see Deploy an Ops Manager Resource. For certificate renewal automation, see Set Up a cert-manager Integration.

External Connectivity

Out of the box, Ops Manager is accessible only within the Kubernetes cluster's internal network. For administrators and monitoring agents running outside the cluster to reach the Ops Manager UI and API, you need to configure external connectivity.

The spec.externalConnectivity block instructs the Kubernetes Operator to create a Kubernetes Service of the specified type. We strongly recommend that you use LoadBalancer when your cloud provider supports it, as it provisions a stable external endpoint automatically. NodePort is a fallback for on-premises or bare-metal clusters, as shown in the following example:

spec:
  externalConnectivity:
    type: LoadBalancer

You can add cloud-specific annotations to influence load balancer behavior. For example, to use an AWS Network Load Balancer on an internal subnet:

spec:
  externalConnectivity:
    type: LoadBalancer
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
      service.beta.kubernetes.io/aws-load-balancer-internal: "true"

If the external endpoint has a custom domain name (for example, https://opsmanager.example.com), set spec.opsManagerURL so that the Kubernetes Operator and its agents use the correct address when communicating with Ops Manager:

spec:
  opsManagerURL: "https://opsmanager.example.com:8443"
  externalConnectivity:
    type: LoadBalancer

For the full set of external connectivity fields, see spec.externalConnectivity in the specification reference.

The Application Database

The Application Database is a MongoDB replica set that stores all of Ops Manager's internal state: project configurations, user accounts, alert definitions, and more. It is tightly coupled to the Ops Manager application servers and must be healthy for Ops Manager to function. The operator manages the Application Database as part of the same custom resource, which means a single YAML manifest controls both the application and its backing database.

Version and Members

You must specify the Application Database version and replica set size. The version uses the format X.Y.Z-ubi8 for Enterprise edition. The -ubi8 suffix ensures the Kubernetes Operator uses the UBI-based container image. Three members is the standard minimum for a production-grade replica set:

spec:
  applicationDatabase:
    members: 3
    version: "8.0.0-ubi8"

Feature Compatibility During Upgrades

When upgrading the Application Database, set featureCompatibilityVersion to your currently deployed version to create a safe rollback point. Once you have confirmed stability on the new binary version, raise the FCV in a subsequent change:

spec:
  applicationDatabase:
    version: "8.0.0-ubi8"
    featureCompatibilityVersion: "7.0"

Authentication and Passwords

You can supply a custom password for the Application Database user through a Kubernetes Secret reference. This is optional; if omitted, the operator manages the password automatically:

spec:
  applicationDatabase:
    passwordSecretKeyRef:
      name: appdb-user-secret
      key: password

Storage and Resources

The Application Database has its own storage and pod specification. Sizing it appropriately depends on how many projects and deployments Ops Manager manages. The default storage claim for Ops Manager is 16Gi. For a small to medium deployment, 50-100 GiB of fast storage is a reasonable starting point. For larger environments, consider separating data and journal volumes:

spec:
  applicationDatabase:
    members: 3
    version: "8.0.0-ubi8"
    podSpec:
      cpu: "2"
      memory: "4Gi"
      persistence:
        multiple:
          data:
            storage: "100Gi"
            storageClass: "fast-ssd"
          journal:
            storage: "30Gi"
            storageClass: "fast-ssd"
          logs:
            storage: "10Gi"
            storageClass: "standard"

Multi-Cluster Application Database

The Application Database can also span multiple Kubernetes clusters for resilience. Set spec.applicationDatabase.topology to MultiCluster and define how many members run in each cluster:

spec:
  applicationDatabase:
    topology: MultiCluster
    version: "8.0.0-ubi8"
    clusterSpecList:
      - clusterName: "cluster-1"
        members: 2
      - clusterName: "cluster-2"
        members: 2
      - clusterName: "cluster-3"
        members: 1

When using MultiCluster topology, the members field at the Application Database level is ignored; each cluster's member count comes from its clusterSpecList entry.

For all Application Database settings, see the specification reference under spec.applicationDatabase.

Backup Infrastructure

Ops Manager provides continuous backup for the MongoDB deployments it manages. Unlike the per-deployment spec.backup.mode flag on a MongoDB CR, the backup settings on the Ops Manager resource define the infrastructure that stores backup data: head databases, oplog stores, and snapshot stores. Without this infrastructure in place, enabling backup on individual MongoDB resources will fail.

Enabling Backup

Set spec.backup.enabled to true to activate the backup subsystem. This alone is not enough; you must also configure at least one oplog store and one snapshot store:

spec:
  backup:
    enabled: true

Head Database

The head database stores backup metadata and job state. Allocate enough storage to accommodate the metadata footprint of all deployments being backed up. For most environments, 30-100 GiB is adequate:

spec:
  backup:
    enabled: true
    headDB:
      storage: "50Gi"
      storageClass: "fast-ssd"

Oplog Stores

Oplog stores capture the MongoDB oplog, which enables point-in-time recovery. Each oplog store is backed by a separate MongoDB deployment (which you create as a regular MongoDB CR). You reference that deployment by name:

spec:
  backup:
    enabled: true
    opLogStores:
      - name: oplog1
        mongodbResourceRef:
          name: oplog-db
        mongodbUserRef:
          name: oplog-user
        assignmentLabels:
          - "production"

S3-backed oplog stores are available for organizations that prefer object storage:

spec:
  backup:
    s3OpLogStores:
      - name: s3-oplog-store
        s3SecretRef:
          name: s3-credentials
        pathStyleAccessEnabled: true
        s3BucketEndpoint: "s3.us-east-1.amazonaws.com"
        s3BucketName: "oplog-bucket"

Snapshot Stores

Snapshot stores hold the periodic full-state snapshots. You can use MongoDB-backed blockstores or S3-backed stores. S3 is often preferred for cost and scalability:

spec:
  backup:
    enabled: true
    s3Stores:
      - name: s3-snapshot-store
        mongodbResourceRef:
          name: s3-metadata-db
        mongodbUserRef:
          name: s3-store-user
        s3SecretRef:
          name: s3-credentials
        pathStyleAccessEnabled: true
        s3BucketEndpoint: "s3.us-east-1.amazonaws.com"
        s3BucketName: "snapshot-bucket"
        assignmentLabels:
          - "production"

MongoDB-backed blockstores follow the same pattern without the S3 fields:

spec:
  backup:
    blockStores:
      - name: blockstore1
        mongodbResourceRef:
          name: blockstore-db
        mongodbUserRef:
          name: blockstore-user

KMIP Encryption for Backups

If your compliance requirements mandate encryption of backup data at rest, you can integrate with a KMIP-compliant key management server:

spec:
  backup:
    enabled: true
    encryption:
      kmip:
        server:
          url: "kmip.example.com:5696"
          ca: "kmip-ca-configmap"
        client:
          clientCertificatePrefix: "kmip-client"

Assignment labels let you route specific MongoDB deployments to specific stores, giving you fine-grained control over where backup data lands.

For the full backup specification, see spec.backup in the specification reference. For step-by-step procedures, see Configure File System Backup Store with Kubernetes Operator and Configure KMIP Backup Encryption for Ops Manager.

Resource Allocation and JVM Tuning

Ops Manager is a Java application, and its resource consumption depends on the number of monitored deployments, the volume of metrics data, and whether backup is enabled. The operator deploys Ops Manager as a StatefulSet, and you control its pod specifications through spec.statefulSet.

At a minimum, set CPU and memory requests and limits. MongoDB recommends at least 4 CPU and 8 GiB of memory for small deployments, scaling up for larger environments:

spec:
  statefulSet:
    spec:
      template:
        spec:
          containers:
            - name: mongodb-ops-manager
              resources:
                requests:
                  cpu: "4"
                  memory: "8Gi"
                limits:
                  cpu: "8"
                  memory: "16Gi"

The operator calculates JVM heap settings based on the container's memory limits. If you need to override Java heap or GC parameters, use spec.jvmParameters, but do so with caution: incorrect heap values can destabilize Ops Manager:

spec:
  jvmParameters:
    - "-Xmx12g"
    - "-Xms8g"
    - "-XX:+UseG1GC"

Warning

Setting memory limits above 32 GiB can cause issues with the backup service due to JVM compressed oops behavior. Keep limits at or below 32 GiB.

For the full StatefulSet specification fields, see spec.statefulSet.spec in the specification reference.

Local and Remote Mode

By default, Ops Manager downloads MongoDB installation binaries from the internet (Remote mode). In air-gapped or restricted-network environments, you can configure Local mode, where binaries are served from a PersistentVolume mounted to the Ops Manager pods, or Remote mode with a custom endpoint.

Remote mode (default):

spec:
  configuration:
    automation.versions.source: "remote"

Local mode (for air-gapped environments):

spec:
  configuration:
    automation.versions.source: "local"
    automation.versions.directory: "/mongodb-ops-manager/mongodb-releases"

For detailed procedures, see Configure an Ops Manager Resource to use Local Mode and Configure an Ops Manager Resource to use Remote Mode.

Iterating on Your Ops Manager Configuration

An Ops Manager custom resource evolves alongside your organization. Common iteration scenarios include upgrading the Ops Manager version, scaling replicas for high availability, adding backup infrastructure for newly deployed databases, and rotating TLS certificates.

Guidelines for safe changes:

Upgrade |onprem| in place. Change spec.version and apply. The operator performs a rolling upgrade of the application pods. Ensure the Application Database version is compatible with the new Ops Manager version before upgrading.
Scale replicas independently. You can increase spec.replicas without downtime. The new pods join the existing service automatically.
Add backup stores incrementally. Define new oplog or snapshot stores in the CR and apply. Existing backup assignments are not affected.
Rotate certificates proactively. Update the TLS certificate Secrets and, if necessary, the CA ConfigMap. The operator detects the changed Secret and restarts the affected pods.
Watch the resource status. After any change, run kubectl get om and inspect the status field for reconciliation progress and any error conditions.

For version upgrade procedures, see Upgrade Ops Manager and Backing Database Versions. For disaster recovery guidance, see Disaster Recovery for Ops Manager and AppDB Resources.

Putting It All Together: A Complete Ops Manager Resource Example

The following example combines the concepts covered on this page into a production-ready Ops Manager deployment. It includes HTTPS, email configuration, a three-member Application Database with split storage, backup with S3 snapshot and oplog stores, KMIP encryption, and resource limits:

apiVersion: mongodb.com/v1
kind: MongoDBOpsManager
metadata:
  name: ops-manager-prod
  namespace: ops-manager
spec:
  replicas: 2
  version: "8.0.0"
  adminCredentials: ops-manager-admin-secret
  opsManagerURL: "https://opsmanager.example.com:8443"
  configuration:
    mms.fromEmailAddr: "ops-manager@example.com"
    mms.replyToEmailAddr: "ops-manager@example.com"
    mms.adminEmailAddr: "admin@example.com"
    mms.mail.hostname: "smtp.example.com"
    mms.mail.port: "587"
    mms.mail.ssl: "true"
    mms.mail.transport: "smtp"
    mms.ignoreInitialUiSetup: "true"
  security:
    certsSecretPrefix: "om-prod"
    tls:
      ca: "om-ca-configmap"
  externalConnectivity:
    type: LoadBalancer
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
  statefulSet:
    spec:
      template:
        spec:
          containers:
            - name: mongodb-ops-manager
              resources:
                requests:
                  cpu: "4"
                  memory: "8Gi"
                limits:
                  cpu: "8"
                  memory: "16Gi"
  jvmParameters:
    - "-Xmx12g"
    - "-Xms8g"
  applicationDatabase:
    members: 3
    version: "8.0.0-ubi8"
    featureCompatibilityVersion: "8.0"
    security:
      certsSecretPrefix: "appdb-prod"
      tls:
        ca: "appdb-ca-configmap"
    podSpec:
      cpu: "4"
      memory: "8Gi"
      persistence:
        multiple:
          data:
            storage: "200Gi"
            storageClass: "fast-ssd"
          journal:
            storage: "50Gi"
            storageClass: "fast-ssd"
          logs:
            storage: "20Gi"
            storageClass: "standard"
  backup:
    enabled: true
    encryption:
      kmip:
        server:
          url: "kmip.example.com:5696"
          ca: "kmip-ca-configmap"
        client:
          clientCertificatePrefix: "kmip-client"
    headDB:
      storage: "100Gi"
      storageClass: "fast-ssd"
    opLogStores:
      - name: oplog1
        mongodbResourceRef:
          name: oplog-db
        mongodbUserRef:
          name: oplog-user
        assignmentLabels:
          - "production"
    s3Stores:
      - name: s3-snapshots
        mongodbResourceRef:
          name: s3-metadata-db
        mongodbUserRef:
          name: s3-store-user
        s3SecretRef:
          name: s3-credentials
        pathStyleAccessEnabled: true
        s3BucketEndpoint: "s3.us-east-1.amazonaws.com"
        s3BucketName: "backup-snapshots-prod"
        assignmentLabels:
          - "production"

Tip

Ops Manager Resource Specification — Complete Ops Manager CR field reference
Deploy an Ops Manager Resource — Step-by-step single-cluster deployment
Deploy Ops Manager Resources on Multiple Kubernetes Clusters — Multi-cluster Ops Manager deployment
Configure an Ops Manager Resource to use Local Mode — Air-gapped deployment
Configure an Ops Manager Resource to use Remote Mode — Remote binary source
Configure File System Backup Store with Kubernetes Operator — File system backup stores
Configure KMIP Backup Encryption for Ops Manager — KMIP backup encryption
Set Up a cert-manager Integration — Automated certificate renewal
Disaster Recovery for Ops Manager and AppDB Resources — Disaster recovery procedures