Allow backup: on workload volumes, not only managed services

Summary

backup: is available only on managed services — the entries that declare a driver, such as postgres. A workload that keeps its own state in a bind-mounted host directory has no declarative backup path at all.

Checked against the onebox.run-v1 schema at v2026.8.17. Workload volumes has no backup property:

.properties.workloads.additionalProperties.properties.volumes
  -> "Managed named volumes or bind mounts. Relative bind sources are read-only
      release content; absolute sources are external host state."

The schema calls these "external host state" and then offers nothing to protect them.

How this looks in a real app

From labstack/monk's ob.yml, the stateful surfaces:

path	workload	contents	backup
/data/qdrant	qdrant	research embeddings	none
/data/monk	tape / server	market bar store	none
/data/kestra/storage	kestra	flow storage	none
/data/cipher	cipher	trading journal and order ledger	none
postgres	service	application database	PITR, 5m max loss, nightly, weekly drill
redis	service	cache	ephemeral by choice

Four of six stateful things in the app have no path to the backup machinery, and the platform already has every piece they would need: a configured backup_targets entry with endpoint, region and failure domain; sops credential resolution; retention.keep; and drill.schedule with max_age.

The workaround, and why it is only adequate sometimes

schedule: on a role: job workload is a genuine answer for simple cases. For an append-only directory of a few hundred kilobytes, a nightly job that uploads a tarball plus a weekly job that extracts it and asserts it parses is proportionate, and arguably better than a platform feature because the verification is specific to the data.

It stops being adequate on three axes:

Consistency. A directory being written during the copy yields a torn read. Postgres avoids this because the driver knows how to quiesce it. A job-based copy of a live vector store or a bar store has no such story, and nothing in the platform signals that the resulting artifact is crash-consistent at best.

Drill. drill.schedule with max_age is the property that separates a backup from a hopeful upload. A job can perform a restore check, but nothing notices when the job stops running. Every app that hand-rolls this will write the upload; few will write the drill, and none will get staleness alerting for free.

Credentials. To write to the configured target, a job workload needs the backup credentials injected as env. That hands an application container the platform's own object-storage write credentials — a materially wider grant than any workload holds today, repeated once per stateful workload. The alternative is a separately provisioned scoped key per app, which is real operational work that exists only because the platform will not perform the write itself.

Proposal

Allow backup: on a workload volume, reusing the existing backup_targets, retention and drill blocks unchanged:

  cipher:
    role: worker
    volumes:
      - source: /data/cipher
        path: /data/cipher
        backup:
          target: offsite
          recovery_kind: snapshot
          exclude: [sessions/]
          quiesce:
            command: [sh, -c, "sync"]
          schedule:
            cron: "0 17 * * 1-5"
            timezone: America/New_York
          retention:
            keep: 14
          drill:
            schedule:
              cron: "0 6 * * 0"
            max_age: 8d

Design intent:

• recovery_kind: snapshot, never pitr. The semantics are weaker than a driver-managed backup and the name should say so, so that nobody plans a recovery around a guarantee this does not provide.
• quiesce — an optional command run in the workload before the copy, and its counterpart after. Trivial or absent for append-only data; meaningful for a store that can be asked for a consistent snapshot.
• drill verifies a restore into a scratch location and reports staleness the same way the service drill does. This is the main reason to build the feature rather than leave it to each app.
• The platform performs the write, so no application container needs backup credentials.
• exclude kept deliberately minimal — a list of path prefixes, nothing resembling a sync DSL.

Explicit non-goals

This should not grow into a general backup product. No deduplication, no incremental chains, no arbitrary include/exclude expressions, no restore-to-arbitrary-target. That is restic or borg, and pulling it into onebox trades a small well-defined capability for a large one that competes with mature tools.

The scope is: copy a declared volume to a declared target on a schedule, expire it on the declared retention, and prove it restores on the declared drill.

Open question

The evidence here is one application. Whether four unbacked volumes is representative of onebox's install base or an artifact of how this app was built is the thing that decides whether this is a platform feature or an app-level pattern. Worth sampling another deployment before committing to it.

Context

labstack/monk#938 tracks the app-level cron job for the case that prompted this. That job is going ahead on its own merits and does not depend on this issue.

No implementation files or tests are named; start by inspecting the onebox.run-v1 schema path for workloads.*.volumes and sampling another deployment, as requested in the open question. Determine whether volume backup is representative and whether the proposed target, quiesce, retention, exclusion, and drill semantics fit the existing service backup machinery; done means a scoped platform decision and implementation plan.