MongoDB Store Configuration

Overview

The MongoDB Store module provides persistent storage for health events collected by NVSentinel monitors. It deploys a MongoDB replica set with TLS encryption and authentication.

Two in-cluster backends are supported: Bitnami (default) and Percona Operator. This page covers Helm configuration for both. If your cluster runs on ARM64 nodes, you must use the Percona backend; see ARM64 support.

Backend selection

Both flags must always be set together. Setting them explicitly in your values, rather than relying on the chart defaults, is recommended for any long-lived installation: it keeps your deployment on its current backend even if the chart default changes in a future release. Upgrading a release across a backend change does not work in place and forces a full remove-and-redeploy migration, so an accidental switch is worth guarding against.

See ADR-013: MongoDB Migration from Bitnami for the rationale behind the dual-backend design and for licensing details.

To use a cloud-managed MongoDB (DocumentDB, Atlas, etc.) instead of in-cluster storage, see External Datastore.

ARM64 support

The Bitnami backend does not work on ARM64 nodes. Its images (bitnamilegacy/mongodb and the related exporter and TLS images) are only published for amd64. On an ARM64 node the MongoDB pod never starts and stays in ImagePullBackOff with an event like:

Failed to pull image "docker.io/bitnamilegacy/mongodb:8.0.3-debian-12-r0": ... no match for platform in manifest: not found

The Percona backend is fully multi-arch. The operator, the MongoDB server and the metrics exporter images all provide arm64 builds, and NVSentinel’s own images are published for both amd64 and arm64. To run NVSentinel on ARM64 nodes, enable the Percona backend at install time:

1
global:
2
  mongodbStore:
3
    enabled: true
4
5
mongodb-store:
6
  useBitnami: false
7
  usePerconaOperator: true

Switching backends on an existing installation

Do NOT switch backends by changing the two flags on a live release with helm upgrade. The upgrade fails partway through with an immutable field error on the database initialization Job, and by then it has already deployed parts of the other backend. The result is two MongoDB clusters running side by side and services pointed at the wrong one.

Switching backends reinstalls the datastore; the migration runbook’s default path carries the health event data over with a dump and restore, and only its opt-out clean path drops it. Follow the MongoDB Bitnami to Percona migration runbook for the full procedure, including the cleanup steps and the handling of in-flight quarantines.

Percona Operator

Enable Percona when first installing NVSentinel. On a release that already runs Percona, keep these flags set on every upgrade. To move an existing Bitnami installation to Percona, do not change the flags in place; follow the migration runbook instead.

1
global:
2
  mongodbStore:
3
    enabled: true
4
5
mongodb-store:
6
  useBitnami: false
7
  usePerconaOperator: true

When Percona is enabled, the replica set is configured under psmdb-db instead of mongodb.* (see defaults in distros/kubernetes/nvsentinel/charts/mongodb-store/values.yaml).

• Service endpoint: mongodb-rs0.\{namespace\}.svc.cluster.local:27017
• Metrics: percona/mongodb_exporter sidecar on port 9216 (configured in default psmdb-db values)
• Operator reference: Percona Operator for MongoDB

The chart-generated MONGODB_URI follows the selected backend automatically (mongodb-headless for Bitnami, mongodb-rs0 for Percona). If you set global.datastore.connection.host explicitly in your values, it must match the backend you selected.

Volume size

The Percona defaults request 8Gi data volumes. Some cloud providers enforce a larger minimum block volume size (OCI block volumes are at least 50Gi, for example). When the provisioned volume ends up larger than the requested size, the operator stops reconciling with requested storage is less than actual storage and the replica set never initializes. Set the volume size explicitly to at least your provider’s minimum:

1
mongodb-store:
2
  psmdb-db:
3
    replsets:
4
      rs0:
5
        volumeSpec:
6
          pvc:
7
            resources:
8
              requests:
9
                storage: "50Gi"

Pod placement (Percona)

The Percona components use their own scheduling keys. Values under mongodb-store.mongodb.* apply only to the Bitnami backend:

1
mongodb-store:
2
  job:
3
    nodeSelector: \{\}
4
    tolerations: []
5
  psmdb-operator:
6
    nodeSelector: \{\}
7
    tolerations: []
8
  psmdb-db:
9
    replsets:
10
      rs0:
11
        nodeSelector: \{\}
12
        tolerations: []

Verify after install:

$
kubectl get perconaservermongodb -n \{namespace\}
$
kubectl get pods -n \{namespace\} -l app.kubernetes.io/component=mongod

The perconaservermongodb resource must reach the ready state and the create-mongodb-database job must complete.

Configuration Reference

Module Enable/Disable

Controls whether the mongodb-store module is deployed in the cluster.

1
global:
2
  mongodbStore:
3
    enabled: true

Initialization Job Placement

Configures node placement for initialization jobs (applies to both backends).

1
mongodb-store:
2
  job:
3
    nodeSelector: \{\}
4
    tolerations: []

Parameters

nodeSelector

Node selector for scheduling MongoDB initialization jobs.

tolerations

Tolerations for MongoDB initialization jobs to run on tainted nodes.

Node Placement

Controls pod scheduling for MongoDB replicas.

1
mongodb-store:
2
  mongodb:
3
    nodeSelector: \{\}
4
    tolerations: []

Parameters

nodeSelector

Node selector for scheduling MongoDB replica pods.

tolerations

Tolerations for MongoDB pods to run on tainted nodes.

Metrics Exporter

Configures MongoDB metrics exporter for monitoring integration.

1
mongodb-store:
2
  mongodb:
3
    metrics:
4
      enabled: true
5
      image:
6
        registry: docker.io
7
        repository: bitnamilegacy/mongodb-exporter
8
        tag: 0.41.2-debian-12-r1

Parameters

enabled

Enable MongoDB metrics exporter sidecar container.

image.repository

Container image for the MongoDB exporter.

image.tag

Image tag for the MongoDB exporter.

The exporter exposes metrics on port 9216 for Prometheus scraping.

Helper Images

Container images used in init containers and sidecars.

1
mongodb-store:
2
  mongodb:
3
    helperImages:
4
      kubectl:
5
        repository: docker.io/bitnamilegacy/kubectl
6
        tag: "1.30.6"
7
        pullPolicy: IfNotPresent
8
      mongosh:
9
        repository: ghcr.io/rtsp/docker-mongosh
10
        tag: "2.5.2"
11
        pullPolicy: IfNotPresent

Parameters

kubectl

Image for Kubernetes operations in init containers (secret creation, certificate management).

mongosh

Image for MongoDB shell operations and database initialization.