MongoDB

Deploy MongoDB on Kubernetes using the official mongo Docker image. Supports standalone single-instance, replica set for high availability, and sharded cluster for horizontal scalability.

Key Features

• Three architectures — standalone, replica set, sharded cluster
• Replica set HA — rs0 with configurable member count and optional arbiter
• Sharded cluster — mongos routers, config servers, and data shards
• Internal keyFile auth — replica set member authentication via shared secret
• Upgrade-safe generated credentials — root credentials and keyFiles are retained with persistent data
• Init scripts — .js and .sh files via /docker-entrypoint-initdb.d/
• WiredTiger tuning — custom mongod.conf via config block
• Prometheus exporter — percona/mongodb_exporter sidecar with ServiceMonitor
• mongodump backup — scheduled S3 backup CronJob
• Pinned upstream image — official MongoDB 9.0.4 patch release

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install my-mongo helmforge/mongodb -f values.yaml

OCI registry:

helm install my-mongo oci://ghcr.io/helmforgedev/helm/mongodb -f values.yaml

Deployment Examples

# values.yaml — MongoDB standalone (single instance)
architecture: standalone

auth:
  enabled: true
  rootUser: root
  existingSecret: mongodb-root-credentials # keys: mongodb-root-username, mongodb-root-password
  users:
    - username: appuser
      password: 'app-password'
      database: myapp
      roles:
        - { role: readWrite, db: myapp }

persistence:
  enabled: true
  size: 20Gi

config:
  storage:
    wiredTiger:
      engineConfig:
        cacheSizeGB: 1 # set to ~50% of available memory minus OS overhead

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

# values.yaml — MongoDB replica set (3 members, HA)
architecture: replicaset

auth:
  enabled: true
  existingSecret: mongodb-root-credentials
  existingKeySecret: mongodb-replica-key # key: mongodb-replica-set-key (must not change)

replicaSet:
  name: rs0
  members: 3

persistence:
  enabled: true
  size: 50Gi

config:
  storage:
    wiredTiger:
      engineConfig:
        cacheSizeGB: 2

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

# Connection string for replica set:
# mongodb://appuser:[email protected]:27017/myapp?replicaSet=rs0

# values.yaml — Replica set with arbiter (2 data members + 1 arbiter)
# Use when you want odd-number election votes without a 3rd data-bearing member
architecture: replicaset

auth:
  enabled: true
  existingSecret: mongodb-root-credentials
  existingKeySecret: mongodb-replica-key

replicaSet:
  name: rs0
  members: 2 # 2 data-bearing members; arbiter provides the 3rd vote

arbiter:
  enabled: true # lightweight pod: votes in elections but stores no data

persistence:
  enabled: true
  size: 50Gi

# values.yaml — MongoDB sharded cluster (2 shards, 3 members each)
architecture: sharded

auth:
  enabled: false

sharded:
  mongos:
    replicaCount: 2 # query routing layer
    port: 27017
  configServer:
    replicaCount: 3 # cluster metadata (must be odd)
    persistence:
      size: 10Gi
  shards:
    count: 2 # number of shards
    membersPerShard: 3 # members per shard replica set
    persistence:
      size: 100Gi

config:
  storage:
    wiredTiger:
      engineConfig:
        cacheSizeGB: 4

Configuration Reference

Image

Authentication

Architecture

Sharded Cluster

Persistence and Configuration

Service

External Secrets

Use External Secrets when root credentials are owned by an external secret manager. Set auth.existingSecret to the same target Secret name so the StatefulSet consumes the synchronized Secret instead of rendering a competing chart-managed Secret.

Metrics

When auth.enabled: false, the exporter now connects without root credentials using mongodb://localhost:27017/admin. With authentication enabled, it keeps using the root credentials from the chart-managed or existing secret.

Pod Security

Backup

Backup uses mongodump (not pg_dump). All databases are dumped and archived.

Upgrade Notes

MongoDB 9.0.4 is a patch in the 9.0 rapid-release line. Before upgrading from 8.3, take a tested backup and confirm every member reports featureCompatibilityVersion: "8.3". Follow the topology-specific upstream procedure, then raise FCV to 9.0 only after all members are healthy and rollback is no longer required. Review the MongoDB 9.0 release notes. The chart reuses generated root credentials and replica set keyFiles across helm upgrade --reset-values and helm upgrade --reuse-values, and retains them when a persistent release is removed. Back up the Secrets together with the PVCs. Rotate credentials with MongoDB administrative commands and a coordinated Secret update instead of changing initialization values.

StatefulSet claim-template sizes are immutable. The chart preserves each installed template size during upgrades, including --reset-values, so a custom-size installation does not fail when defaults are reapplied. Resize the bound PVC through the storage class workflow; changing persistence.size alone does not resize an existing claim or change the size used for PVCs created by future scale-up. Before adding members after expanding existing PVCs, confirm that the retained claim-template size can hold a new member’s initial synchronization.

More Information

• MongoDB Official Documentation
• MongoDB Docker Hub
• HelmForge MongoDB Chart Source