MongoDB Cluster

Template version 2.0.0 is a breaking change, and two of the changes fix defaults that could never fully work.

The template no longer creates a GVC. It deploys into the GVC you install into. The gvc.name and gvc.locations values are gone; locations moved to a top-level locations list.
Never upgrade a 1.x release onto 2.0.0 in place. A 1.x release owns the GVC it created, and Helm deletes what a chart stops declaring — the upgrade destroys that GVC and every workload, volume set and identity inside it, including your data. Migrate to a new release instead: Migrating from 1.x.
The 1.x default was nine members, and MongoDB allows at most seven voters. The 8th and 9th members joined nothing: they ran a healthy-looking mongod, reported ready: true, and were never in the replica set. The default is now one location with three members, and a roster above seven is refused at render. See Locations and Sizing.
backup.mode: physical was removed, and a values file that still sets it fails at render. Its restore could never run. See Backing Up.

Overview

MongoDB Cluster deploys a highly available MongoDB replica set using Percona Server for MongoDB 8.0 into an existing GVC. The cluster provides automatic leader election, self-healing replica membership, and failover across one or more locations. An optional HAProxy workload provides a stable write endpoint that always routes to the current primary. Neither the database credentials nor the replica set keyfile are template values. Both come from secrets you create before installing, so no credential passes through Helm or lands in the release.

Template version 1.1.0 was also a breaking security change. mongodb.username, mongodb.password, mongodb.database and mongodb.replicaSetKey were removed, and an install that still sets any of them fails at render instead of silently falling back to a published default. If you are coming from 1.0.0, read Coming From 1.0.0 as well — its password and keyfile are published values.

Architecture

MongoDB Replica Set — Multi-member cluster with keyfile authentication and automatic replica set initialization. Every member this template creates votes; only the primary accepts writes.
HAProxy (optional, enabled by default) — Leader-routing proxy that health-checks every member and routes traffic to the current primary. Provides a stable connection endpoint that survives failover.
Backup (optional) — Logical backup via mongodump, restored with mongorestore through a port-forward tunnel.

What Gets Created

Stateful MongoDB Workload — (RELEASE_NAME-mongo): a MongoDB container per member per configured location, serving TCP on port 27017 with per-replica DNS for peer discovery.
Volume Set — (RELEASE_NAME-mongo-vs): one persistent ext4 volume per member, mounted at /data/db, with optional capacity autoscaling. A final snapshot is taken on deletion and retained for 7 days.
Identity & Two Policies — (RELEASE_NAME-mongo-identity, RELEASE_NAME-mongo-policy, RELEASE_NAME-mongo-gvc-policy): an identity bound to the workloads, a policy granting it reveal on exactly the two secrets you created plus the chart’s own startup scripts, and a policy granting view on the one GVC you install into so each member can confirm at boot that the GVC really has every location you listed. When backups are enabled, the identity also carries the cloud account binding the backup job uses to reach your bucket.
Startup Secrets — (RELEASE_NAME-mongo-startup, and RELEASE_NAME-mongo-proxy-startup when the proxy is enabled): the chart’s own boot scripts. They hold no credentials.
HAProxy Workload (optional, enabled by default) — (RELEASE_NAME-mongo-proxy): a standard workload routing traffic to the current primary.
Cron Backup Workload (optional) — (RELEASE_NAME-mongo-backup): a scheduled mongodump that writes compressed archives to AWS S3 or GCS, running in one location only.

The template creates no credential secret of its own. The database password and the replica set keyfile live only in the prerequisite secrets described below.

This template does not create a GVC. Every resource lands in the GVC you install into, so cpln workload exec, cpln logs and uninstalling all work against that GVC, and uninstalling can never delete it. Nothing runs in a GVC location you did not list in locations.

Migrating from 1.x

Template versions through 1.1.1 created their own GVC, so that GVC is part of the 1.x release’s manifest. Version 2.0.0 does not declare it — and Helm deletes what a chart stops declaring.

An in-place upgrade from 1.x to 2.0.0 destroys the cluster. Measured on a sibling template with the guard removed: the upgrade deleted the GVC and every workload, volume set and identity inside it in 6 seconds, and reported that the release had been upgraded successfully. Reading the GVC back afterwards returned 404. The volume sets hold your data.The chart ships a render-time refusal so this cannot happen by accident: any leftover gvc key in your values aborts the upgrade before a single API call is made, leaving your cluster untouched and running.

Error: execution error at (mongodb-cluster/templates/identity.yaml:1:4): mongodb-cluster 2.0.0: the
`gvc` values key was REMOVED. This chart no longer creates a GVC -- it deploys into the GVC you
install into, and `gvc.locations` moved to the top-level `locations`. DO NOT `helm upgrade` a 1.x
release onto 2.0.0: the upgrade drops `kind: gvc` from the manifest and Helm deletes what a chart no
longer declares, which DESTROYS that GVC and every workload, volumeset and identity inside it.

The guard cannot cover one case: an upgrade run with no values at all. A 1.x release installed on pure defaults has no gvc key for the chart to see, so nothing fires and the deletion proceeds. Do not run an upgrade of a 1.x release against the 2.0.0 chart under any circumstances — migrate to a new release instead.

Choose the GVC for the new release

Create or pick a GVC and make sure it has exactly the locations you intend to list in locations. See Prerequisites.

Create the prerequisite secrets and install 2.0.0 as a NEW release

Use a different release name: secret names are org-wide, so a same-named release collides with the 1.x one even in another GVC. The new cluster is bootstrapped from the credentials secret on a fresh data directory, so this is the moment to choose a new password — and if you are coming from 1.0.0, you must, because its defaults are published.Re-check your roster while you are here: 1.x defaulted to nine members and only seven of them were ever in the replica set. See Locations and Sizing.

Move the data across

Dump from the old cluster and restore into the new one, tunnelling to each with cpln port-forward. The procedure is the same as Restoring a Backup, with mongodump against the old proxy in place of downloading an archive.

Point your applications at the new release, then uninstall the old one

Uninstall it against the GVC you installed it into, not the one it created: that is where Helm tracks the release, and uninstalling from there takes the created GVC with it.

Values that moved or were removed in 2.0.0. Each one is named at render time rather than ignored, so an old values file produces an error instead of a silent misconfiguration:

1.x	2.0.0
`gvc.name`	Gone. The chart deploys into the GVC you install into
`gvc.locations`	`locations`, at the top level
Backup location derived from `backup.aws.region`	`backup.location`, explicit and validated against `locations`
`backup.mode: physical` and the whole `backup.physical` block	Gone. Its restore could never run — see Backing Up
`locations[].replicas: 0`	Not allowed. Remove the location instead
A total above 7 members, or exactly 2	Not allowed. See the sizing table

Coming From 1.0.0

Template version 1.0.0 took the database credentials as plain Helm values and shipped a working default password, and it shipped a working replica set keyfile as a default too. Both were published in the public template repository, which means every 1.0.0 install that kept the defaults shares one publicly known password and one publicly known keyfile. The keyfile is what replica set members authenticate to each other with, so anyone holding it can join a member to your cluster.

	1.0.0	1.1.0 and later
Database credentials	`mongodb.username`, `mongodb.password`, `mongodb.database` values	`mongodb.credentialsSecretName` — a dictionary secret you create
Replica set keyfile	`mongodb.replicaSetKey` value, with a working default	`mongodb.keyfileSecretName` — an opaque secret you create
Where the secrets live	Rendered into the release by the chart	Created by you, referenced by name, never in the release

The two are deliberately separate secrets: granting an application reveal on the database credentials must not also hand it the key that lets a member join your replica set.

Treat a 1.0.0 cluster’s password and keyfile as compromised, not merely outdated. An unchanged default password (mypassword) and the default replicaSetKey are publicly known, and neither changes by itself when you move off 1.0.0.The migration to 2.0.0 fixes both for free, because it is a new cluster: it is bootstrapped from your new credentials secret on a fresh data directory, and its members authenticate with the new keyfile you generate. So do not carry the 1.0.0 values across — generate both and use the new ones for the new release.

While the old 1.0.0 cluster is still running and you need its credentials to dump from it, read them back out of the secrets that version created:

cpln secret reveal RELEASE_NAME-mongo-config -o yaml

The credential keys are username, password and database. Failing that, they are in the values file you installed 1.0.0 with.

A keyfile cannot be rotated in place on a running cluster, which is why the 1.0.0 key is only fixed by moving to a new release. Members that disagree on the key cannot authenticate to each other, so an in-place rotation means bringing the whole replica set down and back up together. If you must stay on 1.x for now, restrict who can reach the cluster with Firewall and rotate the database password, which you can do online:

db.getSiblingDB("admin").changeUserPassword("admin", "NEW-STRONG-PASSWORD")

Prerequisites

Two secrets must exist before you install. Neither value passes through Helm values, so neither lands in the release. 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. MongoDB is bootstrapped with this user, and this is the credential your applications put in their connection strings:

cpln secret create-dictionary --name my-mongodb-credentials \
  --entry username=admin \
  --entry password='YOUR-STRONG-PASSWORD' \
  --entry database=mydatabase

Set mongodb.credentialsSecretName to the name you used.

Create the replica set keyfile secret

An opaque secret with encoding plain holding the key that replica set members authenticate to each other with. Generate it — do not invent a passphrase:

openssl rand -base64 756 | cpln secret create-opaque --name my-mongodb-keyfile --encoding plain -f -

Set mongodb.keyfileSecretName to the name you used.

Read either secret back later

cpln secret reveal my-mongodb-credentials -o yaml

The keyfile must be valid base64, or the cluster will not start. MongoDB accepts 6–1024 characters from the base64 alphabet only — A-Z, a-z, 0-9, +, / and =. A hand-written passphrase such as change-me-mongodb-key will not boot, because hyphens are outside that alphabet. openssl rand -base64 756 produces 1008 characters, which is the largest generator that still fits under the 1024 limit.The container checks the key at boot and fails with an explicit message naming your secret, before MongoDB is ever started:

FATAL: the keyfile in secret 'my-mongodb-keyfile' contains characters outside the base64 alphabet
(A-Z a-z 0-9 + / =). A passphrase with hyphens or punctuation will NOT work. Regenerate it with:
openssl rand -base64 756

A key that is too short gets its own message: the keyfile in secret 'my-mongodb-keyfile' is 3 characters; mongod requires 6-1024. Both appear in cpln logs only — the workload status shows just Error: exitCode: 1.

Create both secrets before installing. The template refuses to render when either name is blank, but a name pointing at a secret that does not exist installs “successfully” and then wedges: cpln helm install reports every resource created, the workload never becomes ready, and cpln logs shows nothing at all because no container ever starts. The only diagnostic is status.versions[].message:

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

It names the missing secret:

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

Creating the secret does recover the workload on its own — measured at about 6 minutes, so a user who waits only five will wrongly conclude the install is broken.

A GVC Containing Every Location You List

A GVC must already exist, and it must contain every location you list in locations. The requirement is one-directional — the GVC may have more locations than you list, and nothing MongoDB-related runs in those. Check what a GVC has before installing:

cpln gvc get GVC_NAME -o json

The locations are under spec.staticPlacement.locationLinks. To add a missing one:

cpln gvc add-location GVC_NAME --location aws-us-east-2

Every workload in a GVC runs in every location that GVC has, so add locations to a shared GVC deliberately.

A location the GVC does not have is not caught at install time. The platform stores the placement without validating it, so the install succeeds — and the members there simply never start, leaving you with a smaller replica set than the quorum you sized for while HAProxy still carries backends for the members that do not exist.Each member reads the GVC at boot and reports it. A member with an empty data directory refuses to start; one that already holds data warns and keeps serving, so the check can never take a live cluster down:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-mongo"} |= "GVC location check"' --limit 100 --since 15m

GVC locations you did not list run nothing, and no volume is provisioned there. Their deployment reads This workload location is deactivated because maxScale is set to 0. That is the mechanism that keeps a shared GVC safe — it is what a healthy install looks like, not a fault.

Other Prerequisites

For backups: an AWS or GCP cloud account and a storage bucket — see AWS S3 or GCS.

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:

# ─── Locations ────────────────────────────────────────────────────────────────
# This chart deploys into the GVC you install into — it does NOT create one.
# Every location listed here MUST already exist in that GVC. A location the GVC
# lacks contributes HAProxy backends and seed hosts for members that never start,
# so you silently get a smaller replica set than you configured. The members check
# this against the live GVC at boot and say so (see Important Notes in the README).
#
# One entry per location; `replicas` = mongod members in that location.
#
# The default is ONE location with THREE members: the smallest shape that both
# installs on any single-location GVC and survives losing a member. Set it to
# YOUR GVC's locations before installing. MongoDB allows at most 7 VOTING members
# and every member here votes, so the chart refuses a total above 7 (1.x defaulted
# to 9, where the 8th and 9th silently never joined). See the quorum table in the
# README.
locations:
  - name: aws-us-east-1
    replicas: 3

image: percona/percona-server-mongodb:8.0

# Spread each location's members across availability zones. Confirm your
# locations support multi-zone before enabling.
multiZone: false

resources:
  cpu: 1
  memory: 2Gi

# ─── Credentials (prerequisite secrets) ───────────────────────────────────────
# BOTH SECRETS MUST EXIST BEFORE YOU INSTALL — the deployment wedges waiting on a
# secret that does not exist. Neither value passes through Helm values, so neither
# lands in the release. See Prerequisites in the README for the exact commands.
mongodb:
  # `dictionary` secret holding exactly three keys: `username`, `password`,
  # `database`. This is the credential you put in your applications' connection
  # strings, and the root user the cluster is bootstrapped with.
  credentialsSecretName: my-mongodb-credentials

  # `opaque` secret (encoding: plain) holding the replica set keyfile — the shared
  # key cluster members authenticate to each other with. Anyone holding it can join
  # a member to the replica set, so it is kept SEPARATE from the credentials above.
  # CONTENT RULES (mongod rejects anything else): 6-1024 characters from the base64
  # alphabet only — A-Z a-z 0-9 + / = — after whitespace is stripped. Generate with
  # `openssl rand -base64 756`; do NOT invent a passphrase, hyphens alone break it.
  # It CANNOT be changed after the cluster is initialized.
  keyfileSecretName: my-mongodb-keyfile

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

# ─── Access ───────────────────────────────────────────────────────────────────
# There is no public endpoint: MongoDB is reachable on the internal network only.
firewall:
  internalAllowType: same-gvc # options: same-gvc, same-org, workload-list
  workloads: [] # only used with workload-list; this release's own workloads are added automatically
  # - //gvc/GVC_NAME/workload/WORKLOAD_NAME

# ─── HAProxy ──────────────────────────────────────────────────────────────────
# Only the primary accepts writes. The proxy gives clients one stable address and
# routes to whichever member is primary right now.
proxy:
  enabled: true
  image: haproxy:2.9
  resources:
    cpu: 100m
    memory: 128Mi
  minReplicas: 2 # per configured location
  maxReplicas: 2

backup:
  enabled: false
  # `logical` is the only supported mode. Physical (Percona Backup for MongoDB)
  # was removed in 2.0.0: its restore must execute mongod, which the pbm-agent
  # image does not contain, so it wrote backups that could never be restored.
  mode: logical

  schedule: "0 2 * * *" # daily at 2am UTC

  # The ONE location the backup job runs in. Must be one of `locations` above —
  # the platform accepts a location that is not, stores it, and the job then never
  # runs anywhere with nothing to observe. (1.x derived this from backup.aws.region.)
  location: aws-us-east-1

  provider: aws # options: aws or gcp

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

  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 and Sizing

Each entry in locations pairs a location with the number of mongod members to run there. Every location listed must already exist in the GVC you install into; extra GVC locations are ignored. Listing the same location twice, or giving one replicas: 0, is refused at render — to stop running somewhere, remove the entry.

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

The default is one location with three members: the smallest shape that both installs on any single-location GVC and survives losing a member. Set it to your GVC’s locations before installing. Every member this template creates is a voting member, so the total across all locations decides what the replica set survives:

Total members	Majority	Survives	Notes
1	1	nothing	Valid and writable — a single member is always its own primary
2	2	nothing	Refused by this template. Losing either member leaves no primary, so it is strictly worse than 1
3	2	1 member	The usual choice
5	3	2 members
7	4	3 members	The maximum. MongoDB allows at most 7 voting members

A total above 7 is refused at render, because 1.x shipped a default that could not work. The 1.x default was three locations × 3 replicas — nine members. MongoDB rejects the 8th voting member, and the startup script swallowed that error, so members 8 and 9 ran a mongod that passed its health check and reported ready: true while never being in the replica set at all. If you are carrying a 1.x roster forward, re-size it against the table above.

Seven members do not fit in a single location on a default org quota. A replicaDirect workload is capped at 6 replicas per location by the replicas-per-replica-direct-workload quota, and the install is rejected at apply:

One or more containers exceed the autoscaling.maxScale of 6
(quota: replicas-per-replica-direct-workload). Request quota increase

Reach 7 by splitting across locations — 4 + 3 is proven — or request a quota increase. Six in one location is fine.

Spreading members across locations buys survival of a whole location, at the cost of cross-region replication traffic, which is billed. Size it against the same table: 3 locations × 1 member survives losing one location, while 2 locations × 2 members survives losing neither, because 2 of 4 is not a majority.

Never reorder locations after installing — only append. The first entry is the bootstrap location: replica-0 there is the member that initializes the replica set. Moving a different location into first position points that logic at a member with an empty data directory, which can initialize a second, independent replica set.

Adding a location to an existing cluster needs no manual step: new members discover the primary through the seed list and register themselves into the replica set. Add it to the GVC first.

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.credentialsSecretName — Name of the dictionary secret holding username, password and database. The cluster is bootstrapped with this user on first start, and this is the credential your applications use. Must exist before install — see Prerequisites.
mongodb.keyfileSecretName — Name of the opaque secret holding the replica set keyfile. Must exist before install, and its contents must be generated with openssl rand -base64 756.
resources.cpu / resources.memory — Resource limits applied to each MongoDB replica.
image — MongoDB image. Defaults to percona/percona-server-mongodb:8.0.

Neither credential is a Helm value, so neither appears in the release. The two secrets stay separate so that an application granted reveal on the database credentials cannot also read the key that lets a member join the replica set.

The keyfile cannot be changed after the cluster is initialized. It authenticates replica set members to each other; replacing it requires every member to restart with the new key at the same time, which means planned downtime.

The database entry of the credentials secret is for your own connection strings — the cluster is bootstrapped with the admin user, and MongoDB creates a database the first time you write to it.

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 per configured location. Defaults to 2 for availability.
proxy.resources — CPU and memory limits for the proxy workload.
proxy.image — The HAProxy image. Defaults to haproxy:2.9.

Backups do not use the proxy. The backup job connects to replica-0 in backup.location directly, so disabling the proxy does not affect it. The proxy matters for clients that cannot track the primary themselves.

HAProxy’s backends are generated from each location’s own replicas. In 1.x every location got the largest location’s count, so an asymmetric roster such as 3 + 1 produced backends for members that never existed.

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.

The volumes are ext4 on general-purpose SSD. There is no snapshot schedule: a final snapshot is taken when a volume is deleted and kept for 7 days. Use backups for point-in-time copies.

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 the workloads listed in firewall.workloads, plus this release’s own workloads, which the template adds for you.
firewall.workloads — List of your own client workload paths, used only with workload-list.

This list is not only about client traffic: it also governs replication between the members themselves, HAProxy’s health checks and the backup job’s connection. A list naming only your applications would cut the replica set off from itself, so the template always merges its own workloads in — list only your clients.

A firewall change takes roughly 30 seconds to 10 minutes to propagate. After changing firewall.internalAllowType, keep re-testing rather than concluding the knob is broken.

Connecting to MongoDB

Connect using the appropriate endpoint depending on your setup:

Setup	Address	Port
Via HAProxy (writes + reads)	`RELEASE_NAME-mongo-proxy.GVC_NAME.cpln.local`	`27017`
Direct per-member (read-only or internal)	`replica-N.RELEASE_NAME-mongo.LOCATION.GVC_NAME.cpln.local`	`27017`
From your own machine	`cpln port-forward RELEASE_NAME-mongo-proxy 27017:27017 --gvc GVC_NAME`, then `localhost:27017`	`27017`

The username, password and database name are the three entries of your credentials secret. Read them back with:

cpln secret reveal my-mongodb-credentials -o yaml

Example connection string via the proxy:

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

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

mongodb://USERNAME:PASSWORD@replica-0.RELEASE_NAME-mongo.LOCATION.GVC_NAME.cpln.local:27017/DATABASE?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. The cluster has no public endpoint — it is reachable only from inside the org, subject to Firewall.

Failover Behavior

When the primary goes away, the remaining members elect a new one and the proxy re-routes to it. Clients connected through the proxy keep the same connection string and need no change. Measured on a three-member cluster with the primary killed abruptly — a forced shutdown with no step-down, so MongoDB’s own election-timeout path ran rather than a coordinated handover — write availability was restored in 7 seconds or less through the unchanged proxy connection string. Data written before the failover survived, writes after it landed on the new primary, and the killed member rejoined by itself as a secondary about 44 seconds later, restarting in place on its own volume.

Do not lose a member while an upgrade is rolling. A helm upgrade that changes the MongoDB tier restarts it one member at a time, which took about 4 minutes for three members. Losing another member during that window can leave a three-member cluster with one live member and no quorum. Wait for the rollout to finish before performing any other maintenance.

Backing Up

When backup.enabled is true, a cron workload runs mongodump on the configured schedule and uploads a compressed BSON archive to AWS S3 or GCS. Set backup.provider and fill in the matching provider block.

backup:
  enabled: true
  mode: logical          # the only supported mode
  schedule: "0 2 * * *"  # daily at 2am UTC
  location: aws-us-east-1
  provider: aws

backup.location names the one location the job runs in, and it must be one of your locations — the template refuses to render otherwise. That check matters: the platform accepts a placement naming a location that is not there, stores it, and the job then never runs anywhere, with nothing to observe. The job connects to replica-0 in that location directly, not through the proxy, so proxy.enabled: false does not affect it.

backup.mode: physical was removed in 2.0.0, and a values file that still sets it fails at render — including when backup.enabled is false, so an old values file gets the signal immediately rather than on the day someone turns backups on.Its restore could never work. Percona Backup for MongoDB’s physical restore has to execute mongod itself, and the pbm-agent image does not contain that binary:

check mongod binary: run: exec: "mongod": executable file not found in $PATH

Worse, it failed silently: pbm status reported nothing running while the agent kept heartbeating into the bucket, and the failed restore did not appear in pbm list --restore at all. So the mode wrote real-looking snapshots that could never be restored, and gave no sign of it. backup.mode: logical is the supported path, and its restore is verified end to end.

Keep backup.schedule quoted in your values file. Any valid cron expression works, including one beginning with *.

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 1.1.1 narrows AWS backup permissions. This version removes aws::ReadOnlyAccess from the backup identity. That AWS managed policy granted read access to every bucket in your AWS account and contains no write actions at all, so it was never carrying the backup itself — but it was silently supplying any read action your own bucket-scoped policy happened to omit.Update your IAM policy to the full action list below before upgrading. If it already matches, no action is needed. The identity now carries cpln-connector and your bucket-scoped policy only, which is strictly narrower than before. Nothing else changes.

{
    "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/*"
            ]
        }
    ]
}

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

The cluster has no public endpoint, so the restore runs through a cpln port-forward tunnel. You need the MongoDB Database Tools and your cloud CLI on the machine you run it from.

Find and download the archive

List what is in the bucket with aws s3 ls s3://BUCKET_NAME/PREFIX/ (or gcloud storage ls gs://BUCKET_NAME/PREFIX/), then download the one you want:

aws s3 cp s3://BUCKET_NAME/PREFIX/BACKUP_FILE.gz ./backup.gz

Open a tunnel to the proxy

The proxy routes to whichever member is primary right now. Point at RELEASE_NAME-mongo instead if you disabled the proxy. Leave this running.

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

Restore through the tunnel

In another terminal:

mongorestore --uri="mongodb://USERNAME:PASSWORD@localhost:27017/?authSource=admin" \
  --gzip --archive=./backup.gz

Restored data replicates out to the secondaries like any other write.

Template versions before 2.0.0 documented a restore that could not be followed. They told you to run mongorestore from “a client with network access to the cluster” against a *.cpln.local address — an internal DNS name no external machine can resolve. The tunnel above is the working procedure, and it has been run verbatim end to end: archive downloaded, data destroyed, restored, and confirmed replicated to the secondaries.

Physical (PBM) restores are gone, along with backup.mode: physical itself — see Backing Up for why. There is no PBM restore procedure to follow, because there never was a working one.

Scaling

Scaling Up

Increase replicas for a location in locations, or append a location that the GVC already has, and apply the template upgrade. New members connect to the primary through the seed list and self-register into the replica set automatically. Keep the total inside MongoDB’s 7-voting-member limit, and remember that a single location holds at most 6 on a default quota — see Locations and Sizing.

Scaling Down

Scaling down requires manually removing departing members from the replica set configuration first. If stale members are not removed, the replica set config keeps referencing hosts that no longer exist, which distorts elections and quorum.

Before reducing a location’s replicas, connect to the primary and remove each departing member:

rs.remove("replica-N.RELEASE_NAME-mongo.LOCATION.GVC_NAME.cpln.local:27017")

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

Important Notes

Both prerequisite secrets must exist before you install. A missing one wedges the deployment with no log output at all; the only diagnostic is status.versions[].message from cpln workload get-deployments. See Prerequisites.
Generate the keyfile, never invent one. It must be 6-1024 characters from the base64 alphabet (A-Z a-z 0-9 + / =) — a change-me-... style placeholder will not boot. Use openssl rand -base64 756.
The keyfile cannot be changed after the cluster is initialized. Replacing it requires restarting every member with the new key at the same time.
Never upgrade a 1.x release onto 2.0.0 in place — it deletes the GVC the 1.x chart created and everything in it. Migrate to a new release: Migrating from 1.x.
The GVC must contain every location you list, and may contain more. A missing location is not caught at install: the members there never start, leaving a smaller replica set than you sized. Each member checks the GVC at boot — fatal on an empty data directory, a warning on one that already holds data.
At most 7 members in total, and at most 6 in one location. MongoDB allows 7 voting members and the template refuses more; a single location is capped at 6 by a default org quota, so a 7-member set has to be split across locations.
Never reorder locations after install, only append. The first entry is the bootstrap location that initializes the replica set.
Sizing: 3 members is the usual minimum. A 2-member set is refused, because a majority of 2 is 2 and losing either leaves no primary — strictly worse than a single member.
Rotating either secret does not restart anything. A cpln:// reference resolves when a replica starts and is never re-resolved while it lives, so the old value keeps working with no error until you run cpln workload force-redeployment.
An upgrade that changes the MongoDB tier rolls it — about 4 minutes for three members. Avoid other maintenance during that window.
backup.mode: physical was removed in 2.0.0 and now fails at render. Use logical, whose restore is verified end to end.
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.
Data lives on the volume set and survives redeployment, but uninstalling deletes it.

External References

Percona Server for MongoDB

Official documentation for Percona Server for MongoDB

MongoDB Database Tools

mongodump and mongorestore, used for backup and restore

MongoDB Replica Set

MongoDB replica set concepts and administration

Replica Set Members

Member roles and the 7-voting-member limit

MongoDB Connection String

Connection string URI format and options

MongoDB Cluster Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

Architecture

What Gets Created

Migrating from 1.x

Coming From 1.0.0

Prerequisites

A GVC Containing Every Location You List

Other Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Locations and Sizing

Multi-Zone

MongoDB Settings

HAProxy Proxy

Storage

Firewall

Connecting to MongoDB

Failover Behavior

Backing Up

AWS S3

GCS

Restoring a Backup

Scaling

Scaling Up

Scaling Down

Important Notes

External References

Percona Server for MongoDB

MongoDB Database Tools

MongoDB Replica Set

Replica Set Members

MongoDB Connection String

MongoDB Cluster Template

​Overview

​Architecture

​What Gets Created

​Migrating from 1.x

​Coming From 1.0.0

​Prerequisites

​A GVC Containing Every Location You List

​Other Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Locations and Sizing

​Multi-Zone

​MongoDB Settings

​HAProxy Proxy

​Storage

​Firewall

​Connecting to MongoDB

​Failover Behavior

​Backing Up

​AWS S3

​GCS

​Restoring a Backup

​Scaling

​Scaling Up

​Scaling Down

​Important Notes

​External References

Percona Server for MongoDB

MongoDB Database Tools

MongoDB Replica Set

Replica Set Members

MongoDB Connection String

MongoDB Cluster Template

Overview

Architecture

What Gets Created

Migrating from 1.x

Coming From 1.0.0

Prerequisites

A GVC Containing Every Location You List

Other Prerequisites

Installation

Configuration

Locations and Sizing

Multi-Zone

MongoDB Settings

HAProxy Proxy

Storage

Firewall

Connecting to MongoDB

Failover Behavior

Backing Up

AWS S3

GCS

Restoring a Backup

Scaling

Scaling Up

Scaling Down

Important Notes

External References