MongoDB

Overview

MongoDB is a document-oriented NoSQL database for flexible, schema-free data. This template deploys one MongoDB 8 instance (mongo:8.2.3) on a persistent volume, reachable from other workloads in your GVC and optionally from the internet through a direct load balancer, with optional scheduled mongodump backups to AWS S3 or GCS. Database credentials are not template values. MongoDB reads its username, password and database name from a dictionary secret you create before installing, so no password passes through Helm or lands in the release.

This template does not create a GVC. It deploys into an existing GVC that you already have.

This template runs exactly one MongoDB replica. Do not scale it up: additional replicas would be isolated instances, not a replica set. For a highly available replica set, use the MongoDB Cluster template instead.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-mongo`	MongoDB server (stateful, 1 replica, port `27017`)	—
Volume set	`RELEASE_NAME-mongo-vs`	Data directory mounted at `/data/db`, with optional autoscaling	—
Identity	`RELEASE_NAME-mongo-identity`	Identity the workloads run as; carries the Cloud Account binding when backups are on	—
Policy	`RELEASE_NAME-mongo-policy`	Grants the identity `reveal` on your credentials secret (and the backup config secret)	—
Secret	`RELEASE_NAME-mongo-config`	Dictionary holding only the backup bucket and region — no credentials	`backup.enabled: true`
Workload	`RELEASE_NAME-mongo-backup`	Cron job running `mongodump` on a schedule	`backup.enabled: true`

The template creates no credential secret of its own. The username, password and database name live only in the secret you create.

Prerequisites

One secret must exist before you install. It holds the credentials your applications put in their connection strings. Secrets are org-level, so no GVC flag is involved.

Create the database credentials secret

A dictionary secret holding exactly three keys — username, password and database. On first boot MongoDB creates the user in the admin database with the root role; the database entry is the name your applications use in their connection strings (MongoDB creates it on first write):

cpln secret create-dictionary --name SECRET_NAME \
  --entry username=myuser \
  --entry password='YOUR-STRONG-PASSWORD' \
  --entry database=mydb

Set config.credentialsSecretName to this name. Secret names are org-wide, so give each release its own.

Read the secret back later

Pass -o yaml. A bare cpln secret reveal prints only a summary table, not the values:

cpln secret reveal SECRET_NAME -o yaml

Create the secret before installing, or the deployment wedges silently. The template refuses to render when config.credentialsSecretName is blank, but a name that points at a secret which does not exist installs successfully and then never starts. The container never runs, so cpln logs returns zero lines. The one place the reason appears is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-mongo --gvc GVC_NAME -o yaml

The secret SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Use get-deployments — plain cpln workload get has no versions key. Once the secret exists the deployment recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-mongo --gvc GVC_NAME to skip the wait.

Backups need a bucket and a Control Plane Cloud Account before they can be enabled — see Backing Up. Nothing else is required.

Installation

Create the prerequisite secret, then install with the name of that secret:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/mongodb \
  --version 1.4.1 --gvc GVC_NAME \
  --set config.credentialsSecretName=SECRET_NAME

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Each block below is the shipped default for that part of values.yaml.

Image and Resources

image: mongo:8.2.3

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

Credentials

config:
  # REQUIRED PREREQUISITE SECRET — CREATE IT BEFORE YOU INSTALL.
  # A `dictionary` secret holding exactly three keys: `username`, `password`
  # and `database`. If it does not exist at install time the deployment
  # WEDGES silently — `cpln logs` returns nothing at all. See Prerequisites
  # in the README for the exact `cpln secret create-dictionary` command.
  credentialsSecretName: my-mongodb-credentials

The workload reads the secret through cpln://secret/... references, so the values appear in neither the Helm release nor the stored workload spec.

The credentials are applied only on first startup, when the data directory is empty. Changing the secret afterwards does not change the running database — it only changes what the workload presents when it authenticates, which then fails. To rotate on an existing instance, follow Rotating the Password.

Storage

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

Internal Access

internalAccess: # Sets the internal firewall scope - if set to none, replicas will not be able to reach each other
  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
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

Type	Who can connect on port `27017`
`none`	No workload
`same-gvc`	Every workload in the same GVC
`same-org`	Every workload in the organization
`workload-list`	Only the workloads listed under `workloads`

A change to internalAccess can take a few minutes to take effect; re-test rather than trusting the first response.

Direct Load Balancer

directLoadBalancer:
  enabled: false

When true, MongoDB is exposed on the internet on TCP port 27017 through a direct load balancer with a public IP per location. Only enable it with a strong password in place, and prefer internalAccess for applications running in the same GVC.

Backup

backup:
  enabled: false
  image: ghcr.io/controlplane-com/backup-images/mongo-backup:8.0
  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 # folder name where your backups will be stored

  gcp:
    bucket: my-backup-bucket
    cloudAccountName: my-backup-cloudaccount
    prefix: mongodb/backups # folder name where your backups will be stored

The bucket and Cloud Account must exist first — see Backing Up for the per-provider steps and the IAM policy.

Connecting

What	Address	Notes
Internal (same GVC)	`RELEASE_NAME-mongo.GVC_NAME.cpln.local:27017`	Allowed by the default `internalAccess.type: same-gvc`. Always use the fully qualified name.
External	Public IP per location, TCP `27017`	Only when `directLoadBalancer.enabled: true`. Read the address from `status` in `cpln workload get RELEASE_NAME-mongo --gvc GVC_NAME -o yaml`.
Credentials	`cpln secret reveal SECRET_NAME -o yaml`	The `username`, `password` and `database` entries of your prerequisite secret.

The user lives in the admin database, so connection strings must carry authSource=admin:

mongodb://USERNAME:PASSWORD@RELEASE_NAME-mongo.GVC_NAME.cpln.local:27017/DATABASE?authSource=admin

Verify the server from inside the container. The credentials are already in its environment, so nothing is typed on the command line:

cpln workload exec RELEASE_NAME-mongo --gvc GVC_NAME -- sh -c \
  'mongosh --quiet --username "$MONGO_INITDB_ROOT_USERNAME" --password "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin --eval "db.runCommand({ ping: 1 })"'

To use mongosh from your own machine without opening the firewall, forward the port and connect to 127.0.0.1:

cpln port-forward RELEASE_NAME-mongo 27017:27017 --gvc GVC_NAME

mongosh "mongodb://USERNAME:PASSWORD@127.0.0.1:27017/?authSource=admin"

Operations

Backing Up

When backup.enabled is true, the RELEASE_NAME-mongo-backup cron workload runs mongodump on backup.schedule, authenticating with the username and password from your credentials secret. Each run writes one gzip-compressed archive of every database on the instance — not only the one named in your secret — to PREFIX/mongo-YYYY-MM-DDTHH-MM-SSZ.archive.gz in your bucket. Backups do not delete older archives; manage retention with a bucket lifecycle rule.

AWS S3

Create an S3 bucket. Set backup.aws.bucket to its name and backup.aws.region to its region.
If you do not have a Control Plane Cloud Account for AWS, follow the Create a Cloud Account guide. Set backup.aws.cloudAccountName to its name.
Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME, and set backup.aws.policyName to its name. The template attaches this policy to the backup identity and nothing else, so the bucket in it is the only storage the job can reach:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion",
                "s3:GetBucketLocation",
                "s3:AbortMultipartUpload",
                "s3:ListBucketMultipartUploads",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

Set backup.aws.prefix to the folder path for the archives, then set backup.enabled: true and backup.provider: aws.

GCS

Create a GCS bucket. Set backup.gcp.bucket to its name.
If you do not have a Control Plane Cloud Account for GCP, follow the Create a Cloud Account guide. Set backup.gcp.cloudAccountName to its name.
Add the Storage Admin role to the GCP service account associated with the Cloud Account. The template additionally binds the identity to roles/storage.objectAdmin on exactly the bucket in backup.gcp.bucket.
Set backup.gcp.prefix to the folder path for the archives, then set backup.enabled: true and backup.provider: gcp.

Check a run with the container logs of the cron workload; a successful run ends with [INFO] Backup completed: mongo-....archive.gz:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-mongo-backup"}' --limit 50 --since 24h

Restoring a Backup

The archive is a mongodump --archive --gzip file, so it is restored with mongorestore --gzip --archive. The mongo:8.2.3 image already contains mongorestore, and the container already holds the credentials in its environment, so the restore runs inside the database container. Raw binary cannot pass through cpln workload exec intact, so the archive is base64-encoded on the way in.

This procedure matches how the backup job writes its archives and the tools present in the shipped images, but it has not been rehearsed against a live install of this template. Rehearse it on a throwaway release before you depend on it.

Download the archive

From a machine with access to the bucket. For GCS use gsutil cp gs://... instead:

aws s3 cp s3://BUCKET_NAME/PREFIX/mongo-TIMESTAMP.archive.gz ./restore.archive.gz

Copy it into the MongoDB container

--stdin is required; without it the piped data is discarded and the file lands empty:

base64 < ./restore.archive.gz | cpln workload exec RELEASE_NAME-mongo --gvc GVC_NAME --stdin -- \
  sh -c 'base64 -d > /tmp/restore.archive.gz'

The file sits on the container’s ephemeral disk, not on the data volume; check that ls -l /tmp/restore.archive.gz reports the same size as your download before continuing.

Restore

By default mongorestore adds the archive’s documents to the existing collections and keeps any document whose _id already exists. Add --drop to replace each collection with the backup’s contents, or --nsInclude to restore a single database or collection; see the mongorestore reference for both.

cpln workload exec RELEASE_NAME-mongo --gvc GVC_NAME -- sh -c \
  'mongorestore --gzip --archive=/tmp/restore.archive.gz --username "$MONGO_INITDB_ROOT_USERNAME" --password "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin && rm /tmp/restore.archive.gz'

Verify

List the databases with the verification command from Connecting, replacing the --eval expression with db.adminCommand({ listDatabases: 1 }), then spot-check a collection count.

Rotating the Password

The password in the secret is only read on first boot, so a rotation happens inside MongoDB first and the secret is updated to match:

Change it inside MongoDB

cpln workload exec RELEASE_NAME-mongo --gvc GVC_NAME -- sh -c \
  'mongosh --quiet --username "$MONGO_INITDB_ROOT_USERNAME" --password "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin --eval "db.getSiblingDB(\"admin\").changeUserPassword(\"$MONGO_INITDB_ROOT_USERNAME\", \"NEW-STRONG-PASSWORD\")"'

Update the secret

Set the password entry of your dictionary secret to the new value, so that applications reading the secret and the backup job authenticate with it.

Redeploy the workload

A running replica keeps the environment it started with; updating the secret does not restart it. Force a redeployment so the container’s environment — which the commands on this page rely on — matches the secret:

cpln workload force-redeployment RELEASE_NAME-mongo --gvc GVC_NAME

Upgrading from Earlier Versions

Template version 1.4.0 removed config.username and config.password as values: credentials became the prerequisite secret described above. Version 1.4.1 narrows the AWS backup permissions. Both upgrade in place; neither changes the data on the volume.

From 1.3.2 or earlier

	1.3.2 and earlier	1.4.0 and later
Database credentials	`config.username`, `config.password`, `config.database` values	`config.credentialsSecretName` → a dictionary secret you create
Where the password lives	Chart-created secret `RELEASE_NAME-mongo-config`, and the Helm release	Only the secret you create

Carrying the old values forward stops the upgrade. The removed keys are rejected at render, so cpln helm upgrade fails and your existing release is left untouched and running, rather than restarting against a different password:

Error: execution error at (mongodb/templates/identity.yaml:1:4): mongodb: config.username and
config.password were REMOVED — they are now a `dictionary` secret you create, named by
config.credentialsSecretName, holding the keys `username`, `password` and `database`. Delete
them from your values. See Prerequisites in the README.

Read the credentials the database already uses

Credentials are written into the data directory the first time the volume is initialized, so an existing database keeps whatever it was created with. Recover them from your current values file, or from the secret the old version created — before upgrading:

cpln secret reveal RELEASE_NAME-mongo-config -o yaml

Create the prerequisite secret with those same values

Follow Prerequisites, using the existing username, password and database name. Different values here do not change the database — they just leave the workload unable to authenticate.

Remove the old keys from your values

Delete config.username, config.password and config.database, and set config.credentialsSecretName to your secret’s name.

Upgrade, then rotate the password

After the upgrade succeeds, change any password that came from a 1.3.2 default — those defaults were published in the public template repository, so treat them as compromised. Follow Rotating the Password.

RELEASE_NAME-mongo-config no longer holds credentials. From 1.4.0 it is created only when backup.enabled: true, and holds nothing but the bucket and region. Anything outside this release that read the username or password from it by name — another workload’s environment, a policy, or a parent chart bundling MongoDB as a subchart — must be pointed at the secret you create instead. A reference to a key that no longer exists does not fail loudly; it wedges the referring workload silently.

From 1.4.0 with AWS backups

Version 1.4.1 removes aws::ReadOnlyAccess from the backup identity. That AWS managed policy granted read access to every bucket in your AWS account and contained no write actions, so it never carried the backup itself — but it was silently supplying any read action your bucket-scoped policy happened to omit. Before upgrading, make sure your IAM policy contains the full action list under Backing Up; if it already matches, no action is needed. The identity now carries cpln-connector and your bucket-scoped policy only.

Scaling and Availability

The workload is pinned to one replica; raising the replica count is not supported and would produce isolated instances. Scale vertically with resources, and let the volume grow with volumeset.autoscaling. The data volume survives upgrades and restarts, and the template takes a final snapshot (retained 7 days) when the volume set is deleted. For failover and read scaling, use the MongoDB Cluster template.

Troubleshooting

The workload never becomes ready and cpln logs is empty

Symptom: cpln helm install reported success, the deployment never reaches ready, and cpln logs returns no lines. cpln workload get-deployments RELEASE_NAME-mongo --gvc GVC_NAME -o yaml shows under status.versions[].message:

The secret SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Cause: config.credentialsSecretName names a secret that does not exist (or was created in a different org).Fix: Create the secret as shown in Prerequisites, then run cpln workload force-redeployment RELEASE_NAME-mongo --gvc GVC_NAME or wait several minutes for the deployment to recover on its own.

MongoServerError: Authentication failed after changing the secret

Symptom: Clients using the values currently in the secret are rejected with MongoServerError: Authentication failed.Cause: The secret is applied only when the data directory is first initialized. Editing it later changes what clients present, not the user stored in the database.Fix: Authenticate with the credentials the database was created with, then follow Rotating the Password to bring the database and the secret back in line. Also check that the connection string carries authSource=admin.

helm upgrade fails with config.username and config.password were REMOVED

Symptom: cpln helm upgrade exits with the render error quoted under Upgrading from Earlier Versions and nothing is changed.Cause: Your values file still sets config.username or config.password, which 1.4.0 rejects.Fix: Create the prerequisite secret with the existing credentials, delete the two keys, set config.credentialsSecretName, and upgrade again.

Backup run fails with AccessDenied on the S3 upload

Symptom: The cron workload’s logs show mongodump finishing, then An error occurred (AccessDenied) when calling the PutObject operation.Cause: The IAM policy named in backup.aws.policyName is missing an action, or its Resource does not match backup.aws.bucket. From 1.4.1 nothing else on the identity fills the gap.Fix: Update the policy to the full action list under Backing Up with both the bucket ARN and BUCKET/*, then wait for the next scheduled run and check its logs.

Important Notes

Create the credentials secret before installing. A missing secret wedges the deployment with no log output; the only diagnostic is status.versions[].message from cpln workload get-deployments.
Do not scale above one replica. More replicas are isolated instances, not a replica set — use MongoDB Cluster for that.
Credentials apply only on first boot. Changing the secret later does not change the database; rotate inside MongoDB first, then update the secret and redeploy.
Connection strings need authSource=admin. The user is created in the admin database, not in the database named in your secret.
Backups are full-instance dumps written on a schedule with no retention policy of their own; use a bucket lifecycle rule to expire old archives.
Uninstalling deletes the volume set. A final snapshot is taken and retained for 7 days; the release’s data is otherwise gone with it.
Firewall changes are not instant. Allow a few minutes after changing internalAccess or directLoadBalancer before concluding a knob is broken.

External References

MongoDB Documentation

Official MongoDB manual

mongorestore Reference

Options for restoring archives, including —drop and —nsInclude

MongoDB Docker Image

Behavior of the MONGO_INITDB_* variables used by this template

Backup Image Source

Source code for the MongoDB backup container image

MongoDB Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image and Resources

Credentials

Storage

Internal Access

Direct Load Balancer

Backup

Connecting

Operations

Backing Up

Restoring a Backup

Rotating the Password

Upgrading from Earlier Versions

From 1.3.2 or earlier

From 1.4.0 with AWS backups

Scaling and Availability

Troubleshooting

Important Notes

External References

MongoDB Documentation

mongorestore Reference

MongoDB Docker Image

Backup Image Source

MongoDB Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Resources

​Credentials

​Storage

​Internal Access

​Direct Load Balancer

​Backup

​Connecting

​Operations

​Backing Up

​Restoring a Backup

​Rotating the Password

​Upgrading from Earlier Versions

​From 1.3.2 or earlier

​From 1.4.0 with AWS backups

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

MongoDB Documentation

mongorestore Reference

MongoDB Docker Image

Backup Image Source

MongoDB Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image and Resources

Credentials

Storage

Internal Access

Direct Load Balancer

Backup

Connecting

Operations

Backing Up

Restoring a Backup

Rotating the Password

Upgrading from Earlier Versions

From 1.3.2 or earlier

From 1.4.0 with AWS backups

Scaling and Availability

Troubleshooting

Important Notes

External References