Files
cozystack/examples/backups/mongodb/README.md
T
Andrey KolkovandClaude Opus 4.8 dff56aa998 feat(backups): add a native MongoDB (psmdb) backup-strategy driver
Adds a MongoDB (Percona Server for MongoDB / psmdb) backup-strategy driver so
`apps.cozystack.io/MongoDB` reaches feature parity with the CNPG, MariaDB and
ClickHouse native drivers — logical backups, restore-to-differently-named
instances, and point-in-time recovery through the unified
BackupJob/RestoreJob/BackupClass/Plan interface (closes #3545).

The driver orchestrates the operator's PerconaServerMongoDBBackup /
PerconaServerMongoDBRestore CRDs:

- BackupJob: creates a one-shot PerconaServerMongoDBBackup, polls
  status.state, and persists the S3 destination + storage descriptor
  (by-reference, no credentials) onto the Cozystack Backup artifact.
- RestoreJob: drives PerconaServerMongoDBRestore via backupSource (read back
  from the source backup status, snapshot fallback) so the same artifact
  restores in-place or into a differently-named instance; PITR via
  spec.options.pitr (date/latest).

Because psmdb resolves the backup storage by name against the cluster's
spec.backup.storages, the driver names the chart's storage (s3-storage) via the
cozy-default-mongodb Strategy rather than injecting it, and surfaces a clear
Ready=False precondition when a target has backups disabled.

Wiring:
- api/backups/strategy/v1alpha1: MongoDB strategy type + generated CRD/deepcopy.
- internal/backupcontroller: psmdbstrategy_controller + psmdbtypes/mongodbapp
  partial-schema mirrors; dispatch, supported-kinds and scheme registration.
- backupstrategy-controller: cozy-default MongoDB route, cozy-default-mongodb
  Strategy CR, and psmdb.percona.com RBAC.
- apps/mongodb: backup.insecureSkipTLSVerify knob (psmdb s3 storage has no
  CA-bundle field) so backups can target Cozystack's self-signed seaweedfs.

Tests + e2e:
- unit tests for the driver (validation, ensure-idempotency, precondition,
  backupSource resolution, snapshot round-trip, PITR option parsing).
- examples/backups/mongodb + a mongodb-2-backup-roundtrip Chainsaw suite that
  drives run-all.sh end-to-end (sentinel document round-trips through S3 into a
  restored copy while the source stays untouched), per docs/agents/e2e-testing.md.
- docs/operations/backup-classes.md updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Andrey Kolkov <androndo@gmail.com>
2026-08-12 12:00:33 +04:00

4.6 KiB

MongoDB backup / restore example

End-to-end example for backing up and restoring a Cozystack-managed MongoDB application via the strategy.backups.cozystack.io/v1alpha1 MongoDB strategy driver. The driver delegates execution to the Percona Server for MongoDB operator (psmdb.percona.com CRDs, already shipped with Cozystack): backups materialise as PerconaServerMongoDBBackup CRs and restores as PerconaServerMongoDBRestore CRs in the application's namespace; the operator handles the actual percona-backup-mongodb (pbm) logical dump / restore.

Files are numbered so that kubectl apply -f order matches the dependency graph.

Step File Scope Purpose
0 00-bucket.yaml namespaced COSI-backed S3 bucket + backup user.
1 05-mongodb-src.yaml namespaced Source MongoDB application (backups enabled).
2 10-backupjob-adhoc.yaml namespaced One-shot BackupJob for smoke testing.
3 15-plan.yaml namespaced Cron schedule (every 6h).
4 20-mongodb-target.yaml namespaced Empty MongoDB target for to-copy restore.
5 25-restorejob-in-place.yaml namespaced Destructive restore back into the source.
6 30-restorejob-to-copy.yaml namespaced Non-destructive restore into the target.

How MongoDB backups differ from the other drivers

The psmdb operator only services on-demand PerconaServerMongoDBBackup CRs when the cluster has the pbm agents running and a storage declared — which is what backup.enabled: true on the MongoDB application wires up. Unlike the MariaDB / CNPG drivers, the strategy does not inject the storage into the cluster; it only names it (storageName: s3-storage, the storage the chart declares) via the platform's cozy-default-mongodb Strategy. So the application must opt into backups (backup.enabled: true) with the bucket coordinates in its backup.* values. The driver surfaces a clear Ready=False precondition (rather than a silent hang) when the target cluster has backups disabled.

Restores use PerconaServerMongoDBRestore.spec.backupSource, carrying the S3 destination read back from the source backup, so the same artifact restores in-place or into a differently-named instance, and point-in-time recovery is available via spec.options.pitr.

Placeholders

05-mongodb-src.yaml / 20-mongodb-target.yaml carry REPLACE_WITH_PASSWORD, REPLACE_WITH_COSI_BUCKET_NAME, REPLACE_WITH_S3_ENDPOINT (a URL with scheme, e.g. https://seaweedfs-s3.tenant-root:8333), and REPLACE_WITH_S3_ACCESS_KEY / REPLACE_WITH_S3_SECRET_KEY. run-all.sh resolves them from the provisioned Bucket's BucketInfo Secret. insecureSkipTLSVerify: true lets pbm reach Cozystack's default self-signed in-cluster seaweedfs — the psmdb s3 storage has no CA-bundle field (unlike the MariaDB driver's tls.caSecretKeyRef), so skipping verification is the supported way to trust it. Drop it (default false) when the S3 endpoint is signed by a publicly-trusted CA.

Point-in-time recovery

psmdb records an oplog stream between logical backups (pitr). To restore to a timestamp instead of the plain snapshot, add to a RestoreJob:

spec:
  options:
    pitr:
      type: date
      date: "2026-08-05 12:34:56"   # UTC, YYYY-MM-DD HH:MM:SS

Use type: latest (no date) to replay to the newest restorable point.

Run it

# Defaults to NAMESPACE=tenant-root; override for a tenant namespace.
NAMESPACE=tenant-root examples/backups/mongodb/run-all.sh
# Tear everything down afterwards (idempotent).
NAMESPACE=tenant-root examples/backups/mongodb/cleanup.sh

run-all.sh writes a sentinel document into the source, waits for the BackupJob to reach Succeeded, restores to a copy with a to-copy RestoreJob, and asserts the sentinel round-tripped through S3 into the restored copy while the source is left untouched. Set SKIP_RESTORE=1 to stop after a successful backup.

Same-namespace flows are the supported path. Cross-tenant restores (target in tenant-test, source's seaweedfs in tenant-root) are blocked by the per-tenant Cilium egress policy and stay a manual / dev-cluster flow.

Automated e2e

The Chainsaw suite at hack/e2e-chainsaw/mongodb/ drives this same run-all.sh as a second test (mongodb-2-backup-roundtrip), selected by Test-Impact Analysis whenever the mongodb app or the suite changes, and on every release cut. It runs in tenant-root against the in-cluster seaweedfs endpoint — the isolated e2e tenant cannot reach it across the Cilium egress policy, and the external ingress endpoint is an unroutable placeholder in the sandbox.