MongoDB Cluster - Control Plane

Overview

MongoDB Cluster deploys a highly available MongoDB replica set using Percona Server for MongoDB 8.0. The cluster provides automatic leader election, self-healing replica membership, and seamless failover across one or more locations. An optional HAProxy sidecar provides a stable write endpoint that always routes to the current primary.

Architecture

MongoDB Replica Set — Multi-replica cluster with keyfile authentication and automatic replica set initialization. All replicas participate in elections; only the primary accepts writes.
HAProxy (optional, enabled by default) — Leader-routing proxy that performs active health checks across all replicas and routes write traffic to the current primary. Provides a stable connection endpoint that survives failover.
Backup (optional) — Logical backup via mongodump or physical backup via Percona Backup for MongoDB (PBM).

What Gets Created

Stateful MongoDB Workload — A multi-replica MongoDB container per configured location with persistent storage per replica.
Standard HAProxy Proxy Workload (optional, enabled by default) — Routes write traffic to the current primary replica.
Volume Set — One persistent volume per MongoDB replica for data storage.
Identity & Policy — An identity bound to the workload with reveal access to the credential secrets, and cloud storage access when backup is enabled.
Secrets — A dictionary secret holding admin credentials injected at startup.
Cron Backup Workload (optional, logical mode) — A scheduled mongodump job that writes compressed archives to AWS S3 or GCS.
PBM Agent Sidecar + Cron Trigger (optional, physical mode) — A continuously-running pbm-agent sidecar on each MongoDB replica, plus a lightweight cron workload that triggers the backup on schedule.
GVC — A GVC spanning all configured locations.

This template creates its own GVC. Configure gvc.locations in values.yaml before installing.

Prerequisites

At least one Control Plane location to deploy into.
A unique replicaSetKey generated before deploying: openssl rand -base64 32
For backup: an AWS or GCP cloud account and a storage bucket.

Installation

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

Declare templates in your Pulumi programs

Configuration

The default values.yaml for this template:

gvc:
  name: mongodb-gvc
  locations:
    - name: aws-us-east-1
      replicas: 3
    - name: aws-us-west-2
      replicas: 3
    - name: aws-eu-central-1
      replicas: 3

image: percona/percona-server-mongodb:8.0

multiZone: false

resources:
  cpu: 1
  memory: 2Gi

mongodb:
  username: admin
  password: mypassword
  database: mydatabase
  # REQUIRED: Generate with `openssl rand -base64 32`
  replicaSetKey: "Ol0GnqpqntkcnjprS+Pu/1Ji8fcSEKb8f4zkF5c+dEQ="

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false
    maxCapacity: 100
    minFreePercentage: 10
    scalingFactor: 1.2

firewall:
  internalAllowType: same-gvc # options: same-gvc, same-org, workload-list
  workloads: []
  # - //gvc/GVC_NAME/workload/WORKLOAD_NAME

proxy:
  enabled: true
  image: haproxy:2.9
  resources:
    cpu: 100m
    memory: 128Mi
  minReplicas: 2
  maxReplicas: 2

backup:
  enabled: false
  mode: logical # options: logical, physical
  schedule: "0 2 * * *" # daily at 2am UTC
  provider: aws # options: aws or gcp

  logical:
    image: ghcr.io/controlplane-com/backup-images/mongo-backup:8.0
    resources:
      cpu: 100m
      memory: 128Mi

  physical:
    image: percona/percona-backup-mongodb:2.14.0
    resources:      # pbm-agent sidecar (runs continuously)
      cpu: 100m
      memory: 128Mi
    cron:
      resources:    # backup trigger job (runs briefly on schedule)
        cpu: 50m
        memory: 64Mi

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

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

Locations

Configure which Control Plane locations to deploy into and how many replicas to run per location. Each entry in gvc.locations creates a set of MongoDB replicas at that location. Single Location — all replicas in one location. A minimum of 3 replicas is required for majority quorum:

gvc:
  locations:
    - name: aws-us-east-1
      replicas: 3

Multi-Location — distribute replicas across locations for resilience to a full location outage. For production, use 3 locations with 3 replicas each (9 total). Losing an entire location leaves 6 of 9 replicas online — a clear majority — and the cluster continues serving traffic:

gvc:
  locations:
    - name: aws-us-east-1
      replicas: 3
    - name: aws-us-west-2
      replicas: 3
    - name: aws-eu-central-1
      replicas: 3

Aim for an odd total replica count (3, 5, 7, 9) across all locations to guarantee a clear majority in all split-brain scenarios.

Multi-Zone

Set multiZone: true to spread replicas across availability zones within each location, protecting against zone-level failures. Verify your selected location(s) support multi-zone before enabling.

MongoDB Settings

mongodb.username / mongodb.password — Admin credentials. Change these before deploying to production.
mongodb.database — Default database name created at startup.
mongodb.replicaSetKey — Shared secret used to authenticate replica set members to each other. Must be generated before deploying with openssl rand -base64 32. This value must not be changed after the cluster is initialized — doing so requires a full cluster restart.
resources.cpu / resources.memory — Resource limits applied to each MongoDB replica.
image — MongoDB image. Defaults to percona/percona-server-mongodb:8.0.

HAProxy Proxy

HAProxy is enabled by default and strongly recommended. In a MongoDB replica set, only the primary accepts writes — HAProxy provides a stable endpoint that routes all write traffic to the current primary automatically, surviving failover without any client-side changes.

proxy.enabled — Enable or disable the proxy workload.
proxy.minReplicas / proxy.maxReplicas — Number of HAProxy instances. Defaults to 2 for availability.
proxy.resources — CPU and memory limits for the proxy workload.

HAProxy is required when using logical backups (backup.mode: logical). Physical (PBM) backups connect directly to replicas and do not require the proxy.

Storage

volumeset.capacity — Initial volume size in GiB. Minimum is 10.
volumeset.autoscaling.enabled — Set to true to automatically expand volumes as data grows.
volumeset.autoscaling.maxCapacity — Maximum volume size in GiB.
volumeset.autoscaling.minFreePercentage — Percentage of free space that triggers a scale-up.
volumeset.autoscaling.scalingFactor — Multiplier applied to the current capacity when scaling up.

Firewall

firewall.internalAllowType — Controls which workloads can reach MongoDB:
- same-gvc — All workloads in the same GVC (default).
- same-org — All workloads in the org.
- workload-list — Only workloads listed in firewall.workloads.
firewall.workloads — List of specific workload paths when using workload-list.

Connecting to MongoDB

Connect using the appropriate endpoint depending on your setup:

Setup	Hostname	Port
Via HAProxy (writes + reads)	`{release-name}-mongo-proxy.{gvc}.cpln.local`	`27017`
Direct per-replica (read-only or internal)	`replica-{N}.{release-name}-mongo.{location}.{gvc}.cpln.local`	`27017`

Example connection string via proxy:

mongodb://admin:mypassword@{release-name}-mongo-proxy.{gvc}.cpln.local:27017/mydatabase?authSource=admin

To offload reads from the primary, add readPreference=secondaryPreferred to your connection string and connect directly to a replica:

mongodb://admin:mypassword@replica-0.{release-name}-mongo.{location}.{gvc}.cpln.local:27017/mydatabase?authSource=admin&readPreference=secondaryPreferred

Secondary reads may be slightly stale due to replication lag. Use readPreference=primary (the default) when read-your-own-writes consistency is required.

Configure maxPoolSize in your MongoDB driver to prevent connection exhaustion. A per-app-replica pool of 10–50 connections is a reasonable starting point for most workloads.

Backing Up

Two backup modes are available:

Mode	Mechanism	Best For
`logical`	`mongodump` (BSON archives)	Smaller databases, cross-version migrations, selective collection restores
`physical`	Percona Backup for MongoDB (PBM)	Large databases — all replicas participate and upload concurrently

Set backup.enabled: true, choose a mode, set backup.provider, and fill in the corresponding provider block. The backup job region determines where the backup cron workload runs. For AWS, the Control Plane location is automatically derived from backup.aws.region (e.g., us-east-1 → aws-us-east-1). For GCP, the job runs in the first location listed in gvc.locations.

AWS S3

Complete the following in your AWS account before installing:

Create a bucket

Create an S3 bucket and set backup.aws.bucket and backup.aws.region to match.

Set up a Cloud Account

If you do not have one, create a Cloud Account. Set backup.aws.cloudAccountName to its name.

Create an IAM policy

Create an IAM policy with the following JSON (replace YOUR_BUCKET_NAME) and set backup.aws.policyName to its 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/*"
            ]
        }
    ]
}

GCS

Complete the following in your GCP account before installing:

Create a bucket

Create a GCS bucket and set backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account. Set backup.gcp.cloudAccountName to its name.

You must add the Storage Admin role to the GCP service account created for the Cloud Account.

Restoring a Backup

Logical Restore

Run the following from a client with network access to the cluster and access to the bucket. Connect to the proxy workload so writes land on the current primary. AWS S3:

mongorestore \
  --uri="mongodb://USERNAME:PASSWORD@{release-name}-mongo-proxy.{gvc}.cpln.local:27017/?authSource=admin" \
  --gzip \
  --archive=<(aws s3 cp s3://BUCKET_NAME/PREFIX/BACKUP_FILE.gz -)

GCS:

mongorestore \
  --uri="mongodb://USERNAME:PASSWORD@{release-name}-mongo-proxy.{gvc}.cpln.local:27017/?authSource=admin" \
  --gzip \
  --archive=<(gsutil cp gs://BUCKET_NAME/PREFIX/BACKUP_FILE.gz -)

Physical Restore (PBM)

Physical restores require stopping the MongoDB workload and restoring data files directly. All replicas must participate.

Exec into a pbm-agent container

cpln workload exec {release-name}-mongo --gvc {gvc} --location {location} --replica 0 --container pbm-agent -- /bin/sh

List available backups

MONGO_URI="mongodb://${MONGO_INITDB_ROOT_USERNAME}:${MONGO_INITDB_ROOT_PASSWORD}@localhost:27017/admin?replicaSet=rs0&authSource=admin&authMechanism=SCRAM-SHA-256"
pbm list --mongodb-uri="${MONGO_URI}"

Stop the MongoDB workload

Stop the workload via the Control Plane console or CLI before restoring.

Run the restore

pbm restore BACKUP_NAME --mongodb-uri="${MONGO_URI}"

Restart the workload

Restart the MongoDB workload. All replicas will resync automatically.

Scaling

Scaling Up

Increase replicas for a location in values.yaml and apply the template upgrade. New replicas connect to the primary via seed nodes and self-register into the replica set automatically.

Scaling Down

Scaling down requires manually removing departing replicas from the replica set configuration first. If stale members are not removed, the replica set config will reference non-existent hosts, which can affect elections and quorum calculations.

Before reducing the replica count, connect to the primary and remove each departing replica:

rs.remove("replica-{N}.{release-name}-mongo.{location}.{gvc}.cpln.local:27017")

After all departing replicas are removed from the config, apply the template upgrade to reduce the count.

Important Notes

Minimum replicas: Use at least 3 replicas per location for HA. A 2-replica cluster cannot maintain quorum if one replica fails.
Replica set key: The replicaSetKey must be generated before deployment and must not be changed after the cluster is initialized. Changing it requires a full cluster restart.
Odd total replica count: Aim for an odd total number of replicas across all locations (3, 5, 7, 9) to guarantee a clear majority in all failover scenarios.
Read from secondaries: To offload reads from the primary, use readPreference=secondaryPreferred in your connection string. Secondary reads may be slightly stale due to replication lag.
Connection pooling: Configure maxPoolSize in your MongoDB driver to prevent connection exhaustion. A per-app-replica pool of 10–50 is a reasonable starting point.

External References

Percona Server for MongoDB

Official documentation for Percona Server for MongoDB

Percona Backup for MongoDB

Documentation for PBM physical backup and restore

MongoDB Replica Set

MongoDB replica set concepts and administration

MongoDB Connection String

Connection string URI format and options

Documentation Index

​Overview

​Architecture

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Locations

​Multi-Zone

​MongoDB Settings

​HAProxy Proxy

​Storage

​Firewall

​Connecting to MongoDB

​Backing Up

​AWS S3

​GCS

​Restoring a Backup

​Logical Restore

​Physical Restore (PBM)

​Scaling

​Scaling Up

​Scaling Down

​Important Notes

​External References

Percona Server for MongoDB

Percona Backup for MongoDB

MongoDB Replica Set

MongoDB Connection String

Overview

Architecture

What Gets Created

Prerequisites

Installation

Configuration

Locations

Multi-Zone

MongoDB Settings

HAProxy Proxy

Storage

Firewall

Connecting to MongoDB

Backing Up

AWS S3

GCS

Restoring a Backup

Logical Restore

Physical Restore (PBM)

Scaling

Scaling Up

Scaling Down

Important Notes

External References