Skip to content

Commit 9eb8f09

Browse files
androndoclaude
andcommitted
refactor(backups): make MongoDB PITR option uniform with CNPG + warn on unknown restore options
PITR: replace the bespoke spec.options.pitr{type,date} blob with a single spec.options.recoveryTime RFC3339 string, matching the CNPG strategy's option exactly (CNPGRestoreOptions.RecoveryTime). The driver converts recoveryTime to the psmdb Restore's pitr{type:date,date} in the operator's "YYYY-MM-DD HH:MM:SS" UTC format. An empty recoveryTime restores the snapshot as-taken (documented difference from CNPG, whose empty value means latest WAL — a psmdb logical backup is already consistent). A non-RFC3339 recoveryTime fails terminally. Unknown options: parseMongoDBRestoreOptions now also returns the set of spec.options keys the driver does not recognise; reconcileMongoDBRestore emits a UnknownRestoreOption Warning event per unknown key (and logs it) instead of silently ignoring it — so a "recoverytime" typo no longer silently degrades a PITR restore to a snapshot restore. (BackupJob carries no spec.options blob, so there is no backup-path equivalent; the only backup-time input is the free-form BackupClass parameters used as template vars.) Docs + examples updated to recoveryTime; tests cover the RFC3339→UTC mapping, empty/invalid recoveryTime, and unknown-key reporting. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Signed-off-by: Andrey Kolkov <[email protected]>
1 parent 2e1d411 commit 9eb8f09

5 files changed

Lines changed: 141 additions & 77 deletions

File tree

‎docs/operations/backup-classes.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -93,17 +93,15 @@ A full, scripted example (write a marker document, back up, restore to a copy, a
9393

9494
### Point-in-time recovery (MongoDB)
9595

96-
psmdb records an oplog stream between logical backups. A MongoDB `RestoreJob` recovers to a timestamp via `spec.options.pitr`:
96+
psmdb records an oplog stream between logical backups. A MongoDB `RestoreJob` recovers to a timestamp via `spec.options.recoveryTime` — the same option name and RFC3339 format the Postgres/CNPG driver uses, so the two are uniform:
9797

9898
```yaml
9999
spec:
100100
options:
101-
pitr:
102-
type: date
103-
date: "2026-08-05 12:34:56" # UTC, YYYY-MM-DD HH:MM:SS
101+
recoveryTime: "2026-08-05T12:34:56Z" # RFC3339 (UTC), same as the CNPG driver
104102
```
105103

106-
Use `type: latest` (no `date`) to replay to the newest restorable point. `spec.options.restoreTimeoutSeconds` caps how long the driver waits for the operator restore before failing (default 30m).
104+
The driver converts `recoveryTime` to the psmdb oplog target internally. Unlike CNPG (whose empty `recoveryTime` replays WAL to the latest archived point), an empty `recoveryTime` here restores the backup snapshot as taken — a psmdb logical backup is already a consistent point, so "restore this backup" is the safe default. `spec.options.restoreTimeoutSeconds` caps how long the driver waits for the operator restore before failing (default 30m), matching the CNPG option. Any unrecognised key under `spec.options` (e.g. a `recoverytime` typo) is ignored but surfaced as a `UnknownRestoreOption` Warning event on the RestoreJob rather than silently dropped.
107105

108106
## Inspecting the defaults
109107

‎examples/backups/mongodb/25-restorejob-in-place.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
# MongoDB (clusterName = the source's PerconaServerMongoDB). This is
33
# DESTRUCTIVE — the psmdb operator replays the logical dump into the live source
44
# cluster. Applied for documentation parity; run-all.sh drives the
5-
# non-destructive to-copy restore (40) instead. Optionally add a PITR target via
6-
# spec.options (see README).
5+
# non-destructive to-copy restore (30) instead. Optionally add a PITR target via
6+
# spec.options.recoveryTime (RFC3339) — see README.
77
---
88
apiVersion: backups.cozystack.io/v1alpha1
99
kind: RestoreJob

‎examples/backups/mongodb/README.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ silent hang) when the target cluster has backups disabled.
3636
Restores use `PerconaServerMongoDBRestore.spec.backupSource`, carrying the S3
3737
destination read back from the source backup, so the same artifact restores
3838
in-place **or** into a differently-named instance, and point-in-time recovery is
39-
available via `spec.options.pitr`.
39+
available via `spec.options.recoveryTime`.
4040

4141
## Placeholders
4242

@@ -53,17 +53,18 @@ skipping verification is the supported way to trust it. Drop it (default
5353
## Point-in-time recovery
5454

5555
psmdb records an oplog stream between logical backups (pitr). To restore to a
56-
timestamp instead of the plain snapshot, add to a RestoreJob:
56+
timestamp instead of the plain snapshot, add `recoveryTime` (RFC3339, the same
57+
option the CNPG/Postgres driver uses) to a RestoreJob:
5758

5859
```yaml
5960
spec:
6061
options:
61-
pitr:
62-
type: date
63-
date: "2026-08-05 12:34:56" # UTC, YYYY-MM-DD HH:MM:SS
62+
recoveryTime: "2026-08-05T12:34:56Z" # RFC3339 (UTC)
6463
```
6564
66-
Use `type: latest` (no `date`) to replay to the newest restorable point.
65+
An empty/omitted `recoveryTime` restores the backup snapshot as taken. An
66+
unrecognised key under `spec.options` is ignored but reported as a
67+
`UnknownRestoreOption` Warning event on the RestoreJob.
6768

6869
## Run it
6970

‎internal/backupcontroller/psmdbstrategy_controller.go‎

Lines changed: 87 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ import (
55
"context"
66
"encoding/json"
77
"fmt"
8+
"sort"
9+
"strings"
810
"time"
911

1012
corev1 "k8s.io/api/core/v1"
@@ -511,18 +513,28 @@ func (r *RestoreJobReconciler) reconcileMongoDBRestore(ctx context.Context, rest
511513
}
512514

513515
// parseMongoDBRestoreOptions is intentionally permissive (event + log,
514-
// proceed with defaults) for the timeout knob, but a malformed PITR spec is
515-
// load-bearing — restoring to the wrong point silently would be worse than
516-
// failing — so a bad pitr fails terminally below.
517-
options, err := parseMongoDBRestoreOptions(restoreJob.Spec.Options)
516+
// proceed with defaults) for a malformed blob, but a malformed recoveryTime
517+
// is load-bearing — restoring to the wrong point silently would be worse
518+
// than failing — so a bad recoveryTime fails terminally below.
519+
options, unknownKeys, err := parseMongoDBRestoreOptions(restoreJob.Spec.Options)
518520
if err != nil {
519521
logger.Info("malformed restoreJob.spec.options; falling back to defaults", "error", err)
520522
r.Recorder.Eventf(restoreJob, corev1.EventTypeWarning, "MalformedOptions",
521523
"spec.options is not valid JSON; falling back to defaults: %v", err)
522524
}
525+
// Warn (don't fail) on keys the MongoDB driver doesn't recognise: a typo
526+
// like "recoverytime" would otherwise be silently ignored and the restore
527+
// would run to the snapshot instead of the intended point. A Warning event
528+
// gives the tenant a breadcrumb without rejecting an otherwise-valid restore.
529+
for _, k := range unknownKeys {
530+
logger.Info("ignoring unknown restoreJob.spec.options key", "key", k, "known", mongodbKnownRestoreOptionKeys)
531+
r.Recorder.Eventf(restoreJob, corev1.EventTypeWarning, "UnknownRestoreOption",
532+
"spec.options.%s is not a recognised MongoDB restore option and was ignored (known: %s)",
533+
k, strings.Join(mongodbKnownRestoreOptionKeys, ", "))
534+
}
523535
pitr, perr := options.pitrSpec()
524536
if perr != nil {
525-
return r.markRestoreJobFailed(ctx, restoreJob, fmt.Sprintf("invalid restoreJob.spec.options.pitr: %v", perr))
537+
return r.markRestoreJobFailed(ctx, restoreJob, fmt.Sprintf("invalid restoreJob.spec.options.recoveryTime: %v", perr))
526538
}
527539

528540
// Resolve the backup source (destination + S3 config). Prefer the live
@@ -848,38 +860,77 @@ func (r *BackupJobReconciler) getMongoDBApp(ctx context.Context, namespace, name
848860
}
849861

850862
// MongoDBRestoreOptions is the typed shape of RestoreJob.Spec.Options for the
851-
// MongoDB driver. Mirrors the MariaDB strategy's RestoreOptions pattern and
852-
// adds a PITR knob (psmdb supports point-in-time restore on logical backups).
863+
// MongoDB driver. The option surface is kept uniform with the CNPG strategy
864+
// (CNPGRestoreOptions): point-in-time recovery is expressed as a single
865+
// RFC3339 recoveryTime string, and restoreTimeoutSeconds caps the wait.
853866
type MongoDBRestoreOptions struct {
867+
// RecoveryTime is an optional RFC3339 timestamp for point-in-time recovery,
868+
// mirroring the CNPG strategy's spec.options.recoveryTime. When set, the
869+
// driver maps it onto the psmdb Restore's pitr {type: date, date} (converted
870+
// to the operator's "YYYY-MM-DD HH:MM:SS" UTC format). Empty restores the
871+
// backup snapshot as taken (no oplog replay) — note this differs from CNPG,
872+
// whose empty recoveryTime replays WAL to the latest archived point; a psmdb
873+
// logical backup is already a consistent snapshot, so "restore this backup"
874+
// is the safe, always-available default here.
875+
// +optional
876+
RecoveryTime string `json:"recoveryTime,omitempty"`
877+
854878
// RestoreTimeoutSeconds caps the time the driver waits for the
855879
// PerconaServerMongoDBRestore to terminate before it marks the RestoreJob
856-
// Failed. Zero or unset falls back to psmdbDefaultRestoreDeadline.
880+
// Failed. Zero or unset falls back to psmdbDefaultRestoreDeadline. Same knob
881+
// and semantics as the CNPG strategy.
857882
// +optional
858883
RestoreTimeoutSeconds int64 `json:"restoreTimeoutSeconds,omitempty"`
859-
860-
// PITR requests a point-in-time restore. Type is "date" (Date required,
861-
// format "YYYY-MM-DD HH:MM:SS") or "latest" (Date must be empty). Unset
862-
// restores the backup snapshot as-is.
863-
// +optional
864-
PITR *MongoDBRestorePITR `json:"pitr,omitempty"`
865-
}
866-
867-
// MongoDBRestorePITR mirrors the psmdb restore pitr spec at the RestoreJob
868-
// options boundary.
869-
type MongoDBRestorePITR struct {
870-
Type string `json:"type,omitempty"`
871-
Date string `json:"date,omitempty"`
872884
}
873885

874-
func parseMongoDBRestoreOptions(opts *runtime.RawExtension) (MongoDBRestoreOptions, error) {
886+
// mongodbKnownRestoreOptionKeys enumerates the JSON keys parseMongoDBRestoreOptions
887+
// recognises. Any other key in spec.options is surfaced as a Warning event
888+
// (see reconcileMongoDBRestore) so a typo like "recoverytime" is not silently
889+
// dropped. Keep in sync with the MongoDBRestoreOptions json tags.
890+
var mongodbKnownRestoreOptionKeys = []string{"recoveryTime", "restoreTimeoutSeconds"}
891+
892+
// parseMongoDBRestoreOptions decodes RestoreJob.Spec.Options into the typed
893+
// shape and additionally reports any keys the driver does not recognise. The
894+
// typed decode stays permissive (unknown keys are ignored, not rejected), so
895+
// the returned options are always usable; the unknownKeys slice lets the caller
896+
// warn without failing. A malformed blob returns the zero options + a decode
897+
// error the caller surfaces as an event. Mirrors parseCNPGRestoreOptions, plus
898+
// the unknown-key detection.
899+
func parseMongoDBRestoreOptions(opts *runtime.RawExtension) (MongoDBRestoreOptions, []string, error) {
875900
var out MongoDBRestoreOptions
876901
if opts == nil || len(opts.Raw) == 0 {
877-
return out, nil
902+
return out, nil, nil
878903
}
879904
if err := json.Unmarshal(opts.Raw, &out); err != nil {
880-
return MongoDBRestoreOptions{}, fmt.Errorf("decode restoreJob.spec.options: %w", err)
905+
return MongoDBRestoreOptions{}, nil, fmt.Errorf("decode restoreJob.spec.options: %w", err)
881906
}
882-
return out, nil
907+
// Second pass into a generic map to diff keys against the known set. Done
908+
// separately from the typed decode so the options stay usable even when an
909+
// unknown key is present.
910+
unknown := unknownJSONKeys(opts.Raw, mongodbKnownRestoreOptionKeys)
911+
return out, unknown, nil
912+
}
913+
914+
// unknownJSONKeys returns the top-level object keys in raw that are not in
915+
// known. Returns nil when raw is not a JSON object (a malformed blob is handled
916+
// by the typed decode's error path, not here).
917+
func unknownJSONKeys(raw []byte, known []string) []string {
918+
var obj map[string]json.RawMessage
919+
if err := json.Unmarshal(raw, &obj); err != nil {
920+
return nil
921+
}
922+
knownSet := make(map[string]struct{}, len(known))
923+
for _, k := range known {
924+
knownSet[k] = struct{}{}
925+
}
926+
var out []string
927+
for k := range obj {
928+
if _, ok := knownSet[k]; !ok {
929+
out = append(out, k)
930+
}
931+
}
932+
sort.Strings(out)
933+
return out
883934
}
884935

885936
func (o MongoDBRestoreOptions) effectiveRestoreDeadline() time.Duration {
@@ -889,27 +940,19 @@ func (o MongoDBRestoreOptions) effectiveRestoreDeadline() time.Duration {
889940
return psmdbDefaultRestoreDeadline
890941
}
891942

892-
// pitrSpec translates the options PITR knob into the operator restore spec,
893-
// validating the type/date combination. Returns (nil, nil) when no PITR is
894-
// requested.
943+
// pitrSpec translates the RFC3339 recoveryTime into the operator restore's
944+
// pitr {type: date, date} shape, converting to psmdb's "YYYY-MM-DD HH:MM:SS"
945+
// UTC format (the operator CRD's XValidation regex). Returns (nil, nil) when no
946+
// recoveryTime is requested (plain snapshot restore). A recoveryTime that does
947+
// not parse as RFC3339 is a terminal error — a silent wrong-point restore is
948+
// worse than failing.
895949
func (o MongoDBRestoreOptions) pitrSpec() (*psmdbtypes.PITRSpec, error) {
896-
if o.PITR == nil {
950+
if o.RecoveryTime == "" {
897951
return nil, nil
898952
}
899-
switch o.PITR.Type {
900-
case "date":
901-
if o.PITR.Date == "" {
902-
return nil, fmt.Errorf("pitr.type=date requires pitr.date (format \"YYYY-MM-DD HH:MM:SS\")")
903-
}
904-
return &psmdbtypes.PITRSpec{Type: "date", Date: o.PITR.Date}, nil
905-
case "latest":
906-
if o.PITR.Date != "" {
907-
return nil, fmt.Errorf("pitr.type=latest must not set pitr.date")
908-
}
909-
return &psmdbtypes.PITRSpec{Type: "latest"}, nil
910-
case "":
911-
return nil, fmt.Errorf("pitr.type is required (\"date\" or \"latest\") when pitr is set")
912-
default:
913-
return nil, fmt.Errorf("pitr.type=%q is not supported (use \"date\" or \"latest\")", o.PITR.Type)
953+
t, err := time.Parse(time.RFC3339, o.RecoveryTime)
954+
if err != nil {
955+
return nil, fmt.Errorf("recoveryTime %q is not a valid RFC3339 timestamp: %w", o.RecoveryTime, err)
914956
}
957+
return &psmdbtypes.PITRSpec{Type: "date", Date: t.UTC().Format("2006-01-02 15:04:05")}, nil
915958
}

‎internal/backupcontroller/psmdbstrategy_controller_test.go‎

Lines changed: 42 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -265,10 +265,13 @@ func TestResolveMongoDBRestoreTarget(t *testing.T) {
265265

266266
func TestParseMongoDBRestoreOptionsAndPITR(t *testing.T) {
267267
t.Run("empty options are permissive", func(t *testing.T) {
268-
o, err := parseMongoDBRestoreOptions(nil)
268+
o, unknown, err := parseMongoDBRestoreOptions(nil)
269269
if err != nil {
270270
t.Fatalf("parse nil options: %v", err)
271271
}
272+
if len(unknown) != 0 {
273+
t.Errorf("no unknown keys expected, got %v", unknown)
274+
}
272275
if o.effectiveRestoreDeadline() != psmdbDefaultRestoreDeadline {
273276
t.Errorf("default deadline mismatch: %v", o.effectiveRestoreDeadline())
274277
}
@@ -278,37 +281,56 @@ func TestParseMongoDBRestoreOptionsAndPITR(t *testing.T) {
278281
}
279282
})
280283
t.Run("malformed json errors", func(t *testing.T) {
281-
if _, err := parseMongoDBRestoreOptions(&runtime.RawExtension{Raw: []byte("{not-json")}); err == nil {
284+
if _, _, err := parseMongoDBRestoreOptions(&runtime.RawExtension{Raw: []byte("{not-json")}); err == nil {
282285
t.Fatal("expected decode error")
283286
}
284287
})
285-
t.Run("pitr date valid", func(t *testing.T) {
286-
o := MongoDBRestoreOptions{PITR: &MongoDBRestorePITR{Type: "date", Date: "2026-08-05 12:34:56"}}
288+
t.Run("known keys parse with no unknowns", func(t *testing.T) {
289+
o, unknown, err := parseMongoDBRestoreOptions(&runtime.RawExtension{
290+
Raw: []byte(`{"recoveryTime":"2026-08-05T12:34:56Z","restoreTimeoutSeconds":600}`),
291+
})
292+
if err != nil {
293+
t.Fatalf("parse: %v", err)
294+
}
295+
if len(unknown) != 0 {
296+
t.Errorf("expected no unknown keys, got %v", unknown)
297+
}
298+
if o.RecoveryTime != "2026-08-05T12:34:56Z" || o.RestoreTimeoutSeconds != 600 {
299+
t.Errorf("options mismatch: %#v", o)
300+
}
301+
})
302+
t.Run("unknown keys are reported (typo guard)", func(t *testing.T) {
303+
_, unknown, err := parseMongoDBRestoreOptions(&runtime.RawExtension{
304+
Raw: []byte(`{"recoverytime":"oops","bogus":1}`),
305+
})
306+
if err != nil {
307+
t.Fatalf("parse: %v", err)
308+
}
309+
// sorted: bogus, recoverytime
310+
if len(unknown) != 2 || unknown[0] != "bogus" || unknown[1] != "recoverytime" {
311+
t.Errorf("unknown keys: got %v want [bogus recoverytime]", unknown)
312+
}
313+
})
314+
t.Run("recoveryTime RFC3339 maps to psmdb date in UTC", func(t *testing.T) {
315+
// A non-UTC offset must be normalised to UTC in the psmdb date format.
316+
o := MongoDBRestoreOptions{RecoveryTime: "2026-08-05T14:34:56+02:00"}
287317
pitr, err := o.pitrSpec()
288318
if err != nil {
289319
t.Fatalf("pitrSpec: %v", err)
290320
}
291321
if pitr == nil || pitr.Type != "date" || pitr.Date != "2026-08-05 12:34:56" {
292-
t.Errorf("pitr mismatch: %#v", pitr)
322+
t.Errorf("pitr mismatch: %#v (want date=2026-08-05 12:34:56)", pitr)
293323
}
294324
})
295-
t.Run("pitr date without date errors", func(t *testing.T) {
296-
o := MongoDBRestoreOptions{PITR: &MongoDBRestorePITR{Type: "date"}}
297-
if _, err := o.pitrSpec(); err == nil {
298-
t.Fatal("expected error for date type without date")
299-
}
300-
})
301-
t.Run("pitr latest with date errors", func(t *testing.T) {
302-
o := MongoDBRestoreOptions{PITR: &MongoDBRestorePITR{Type: "latest", Date: "2026-08-05 12:34:56"}}
303-
if _, err := o.pitrSpec(); err == nil {
304-
t.Fatal("expected error for latest type with a date")
325+
t.Run("empty recoveryTime yields no pitr (snapshot restore)", func(t *testing.T) {
326+
pitr, err := MongoDBRestoreOptions{}.pitrSpec()
327+
if err != nil || pitr != nil {
328+
t.Errorf("expected nil pitr: pitr=%#v err=%v", pitr, err)
305329
}
306330
})
307-
t.Run("pitr latest valid", func(t *testing.T) {
308-
o := MongoDBRestoreOptions{PITR: &MongoDBRestorePITR{Type: "latest"}}
309-
pitr, err := o.pitrSpec()
310-
if err != nil || pitr == nil || pitr.Type != "latest" {
311-
t.Errorf("latest pitr mismatch: pitr=%#v err=%v", pitr, err)
331+
t.Run("malformed recoveryTime errors terminally", func(t *testing.T) {
332+
if _, err := (MongoDBRestoreOptions{RecoveryTime: "2026-08-05 12:34:56"}).pitrSpec(); err == nil {
333+
t.Fatal("expected error for non-RFC3339 recoveryTime")
312334
}
313335
})
314336
t.Run("custom deadline honoured", func(t *testing.T) {

0 commit comments

Comments
 (0)