Managed restore of a tenant volume from a recovery point.
curl --request POST \ --url https://stratum.example.com/v1/backup/admin/volumes/example/restore-from \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "recoveryPointId": "example", "ageIdentity": "example" }'Cedar action backup:Manage. the MANAGED
tenant-data restore. Given a volume-scoped recoveryPointId and the
operator’s off-cluster age identity, the control plane fetches the
bundle from the configured volume target (NFS/directory or S3/R2),
decrypts it in memory, and imports it into the volume’s backing image.
This replaces the raw POST.../restore pipe (operator runs
age -d | curl) with a single call.
The identity is used transiently: it is never persisted or logged.
Asynchronous — the request is validated synchronously and
returns 202; the multi-GB import then runs detached. Poll the returned
operationId (a storage.volume.restore operation) for byte-progress
and the final outcome.
400 for a malformed body, a wrong/typo’d identity, a non-volume
recovery point, or an empty/truncated source stream;
404 when the recovery point or its bundle is missing; 409 when the
backing image still exists (nothing was lost); 422 (BackupRefused)
when this control plane cannot import it: the driver cannot, the
volume is node-local on another node, or the point is an incremental
chain the driver cannot apply. Every refusal is answered here, before
the 202; a 202’s operation fails only on the import itself.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
The volume-scoped recovery point to restore (rp-…).
The operator’s off-cluster age private key (“AGE-SECRET-KEY-1…”). Used only in memory to decrypt the fetched bundle; never stored or logged.
Example generated
{ "recoveryPointId": "example", "ageIdentity": "example"}Responses
Section titled “Responses”Accepted — validated synchronously; the import runs asynchronously.
Poll operationId (a storage.volume.restore operation) for
byte-progress and the final outcome.
object
Example
{ "status": "accepted"}INVALID_BODY / INVALID_INPUT — a malformed body or identity, a
non-volume or unrestorable recovery point, missing shape fields, or
an empty/truncated stream. ENCRYPTED_RESTORE_IN_PLACE_ONLY
— the recovery point holds an encrypted volume, which only that
volume’s key opens: restore it in place onto that volume.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Resource not found.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Conflicting state.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}The volume backup or restore cannot run on this control plane, refused
before anything is started. code says why:
BACKUP_UNSUPPORTED— the volume’s (or the target class’s) storage driver cannot export or import a backup.VOLUME_NOT_ON_THIS_NODE— the volume is node-local (lvm-thin) and on another node than the control plane that took the request; a node-local volume is backed up and restored only on its own node. Send the request to that node’s control plane.CHAIN_RESTORE_UNSUPPORTED— an incremental (base/diff) recovery point onto a driver that cannot apply a diff chain (lvm-thin). Restore a full recovery point instead.
A plan run, which backs up later on the leader, cannot refuse up front:
the same BACKUP_UNSUPPORTED / VOLUME_NOT_ON_THIS_NODE arrive as the
failed recovery point’s errorCode and its operation’s error code.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}