Skip to main content

​
Overview

MongoDB is a document-oriented NoSQL database designed for flexible, schema-free data storage at scale. This template deploys a single-replica MongoDB instance with persistent storage and optional external access via a direct load balancer.
MongoDB on Control Plane operates as a single-replica deployment. Do not scale up the replica count, as this would result in multiple isolated instances rather than a replicated cluster.

​
What Gets Created

  • Stateful MongoDB Workload — A single-replica MongoDB container with configurable resources.
  • Volume Set — Persistent storage for MongoDB data, with optional autoscaling.
  • Secret — A dictionary secret storing the admin username, password, and database name, injected into the container at startup.
  • Identity & Policy — An identity bound to the workload with reveal access to the database credentials secret, and cloud storage access when backup is enabled.
  • Backup Cron Workload (optional) — A scheduled mongodump backup job that writes compressed archives to AWS S3 or GCS.
This template does not create a GVC. You must deploy it into an existing GVC.

​
Installation

This template has no external prerequisites unless backup is enabled. To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations
Pulumi Icon Streamline Icon: https://streamlinehq.com

Pulumi

Declare templates in your Pulumi programs

​
Configuration

The default values.yaml for this template: 
image: mongo:8.2.3

resources:
  minCpu: 200m
  minMemory: 256Mi
  maxCpu: 500m
  maxMemory: 512Mi

config: # initdb credentials and database name
  username: username
  password: password
  database: test

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # Set to true to enable autoscaling
    maxCapacity: 100 # Maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # Minimum free percentage to trigger scaling when autoscaling is enabled
    scalingFactor: 1.2 # Scaling factor to determine how much to scale up when autoscaling is triggered

internalAccess: # Sets the internal firewall scope
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads:  # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

directLoadBalancer:
  enabled: false

backup:
  enabled: false
  image: controlplanecorporation/mongo-backup:1.0 # compatible with all MongoDB versions
  schedule: "0 2 * * *"   # daily at 2am UTC

  resources:
    cpu: 100m
    memory: 128Mi

  provider: aws # Options: aws or gcp

  aws:
    bucket: my-backup-bucket
    region: us-east-1
    cloudAccountName: my-backup-cloudaccount
    policyName: my-backup-policy
    prefix: mongodb/backups

  gcp:
    bucket: my-backup-bucket
    cloudAccountName: my-backup-cloudaccount
    prefix: mongodb/backups

​
Credentials

  • config.username — MongoDB admin username. Change before deploying to production.
  • config.password — MongoDB admin password. Change before deploying to production.
  • config.database — Name of the initial database to create (default: test).
These values are only applied on first startup when the data directory is empty. Updating them after the initial deployment will have no effect on the running database. To change credentials on an existing instance, use MongoDB’s native commands (e.g. db.updateUser()).

​
Resources

  • resources.minCpu / resources.minMemory — Minimum CPU and memory guaranteed to the workload.
  • resources.maxCpu / resources.maxMemory — Maximum CPU and memory the workload can use.

​
Storage

  • volumeset.capacity — Initial volume size in GiB (minimum 10).
  • volumeset.autoscaling.enabled — Automatically expand the volume as it fills. When enabled:
    • maxCapacity — Maximum volume size in GiB.
    • minFreePercentage — Trigger a scale-up when free space drops below this percentage.
    • scalingFactor — Multiply the current capacity by this factor when scaling up.

​
Internal Access

  • internalAccess.type — Controls which workloads can connect to MongoDB on port 27017:
TypeDescription
noneNo internal access allowed
same-gvcAllow access from all workloads in the same GVC
same-orgAllow access from all workloads in the same organization
workload-listAllow access only from specific workloads listed in workloads

​
Direct Load Balancer

  • directLoadBalancer.enabled — When true, exposes MongoDB externally on port 27017 via a dedicated load balancer IP.

​
Connecting to MongoDB

Once deployed, connect to MongoDB from within the same GVC using: 
RELEASE_NAME-mongo.GVC_NAME.cpln.local:27017

​
Backup

Backup is disabled by default. When enabled, a cron workload runs mongodump on the configured schedule and uploads compressed archives to AWS S3 or GCS. The backup image is compatible with all MongoDB versions.
  • backup.enabled — Enable scheduled backups.
  • backup.schedule — Cron expression for backup frequency (default: daily at 2am UTC).
  • backup.provider — aws or gcp.
  • backup.resources.cpu / backup.resources.memory — Resources for the backup cron container.

​
AWS S3

Before enabling backup with provider: aws, complete the following in your AWS account:
  1. Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
  2. If you do not have a Cloud Account set up, refer to the docs to Create a Cloud Account. Set backup.aws.cloudAccountName to its name.
  3. Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}
  1. Set backup.aws.policyName to the name of the policy created in step 3.
  2. Set backup.aws.prefix to the folder path where backups will be stored.

​
GCS

Before enabling backup with provider: gcp, complete the following in your GCP account:
  1. Create a GCS bucket. Set backup.gcp.bucket to its name.
  2. If you do not have a Cloud Account set up, refer to the docs to Create a Cloud Account. Set backup.gcp.cloudAccountName to its name.
  3. Add the Storage Admin role to the GCP service account associated with the Cloud Account.
  4. Set backup.gcp.prefix to the folder path where backups will be stored.

​
Restoring a Backup

Run the following from a client with access to the backup bucket. For GCS, replace aws s3 cp s3://... with gsutil cp gs://.... 
aws s3 cp s3://BUCKET_NAME/PREFIX/BACKUP_FILE.gz - \
  | gunzip \
  | mongorestore \
      --host=RELEASE_NAME-mongo.GVC_NAME.cpln.local \
      --port=27017 \
      --username=USERNAME \
      --archive

​
External References

MongoDB Documentation

Official MongoDB documentation

Backup Image Source

Source code for the MongoDB backup container image

MongoDB Template

View the source files, default values, and chart definition