Restore a tenant volume's data from a decrypted backup image.

POST

/v1/backup/admin/volumes/{volumeId}/restore

Code sample: Shell / cURL

curl --request POST \
  --url https://stratum.example.com/v1/backup/admin/volumes/example/restore \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/octet-stream' \
  --data binary

• A Stratum cluster endpoint.

Cedar action backup:Manage. recreates the volume’s backing image (Ceph RBD rbd import) from the request BODY, which must be the age-DECRYPTED export stream. The operator runs age -d -i identity.txt <bundle>.img.age locally (the age identity stays off-cluster — the control plane never decrypts) and streams the plaintext image here. Targets an EXISTING volume whose backing data was lost (e.g. after full-site DR, once the cluster-state restore brought the volume row back). Synchronous — the import runs for the request’s lifetime (a large image takes minutes).

This is the RAW primitive (identity never leaves the operator’s host). For the managed flow — the control plane fetches the bundle from the target and decrypts it itself given the identity — use POST.../restore-from.

400 when the imported stream is empty or shorter than the volume’s provisioned size (a botched decrypt/truncated stream — the corrupt image is rolled back,); 422 (BackupRefused) when the volume’s driver cannot import or the volume is node-local on another node; 409 when the backing image still exists (nothing was lost — refuse rather than clobber live data); 404 for an unknown volume.

Authorizations

• bearerAuth

Parameters

Path Parameters

volumeId

required

string

Request Body^required

The age-decrypted raw RBD image export stream.

Media typeapplication/octet-stream

string format: binary

Responses

200

Volume data restored.

Media typeapplication/json

object

status

required

string

Allowed values: restored

volumeId

required

string

bytesImported

required

integer format: int64

Example

{
  "status": "restored"
}

404

Resource not found.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

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.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

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

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

409

Conflicting state.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

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.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

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

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}

422

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.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

>= 400 <= 599

detail

string

instance

string format: uri-reference

requestId

required

string

code

required

string

issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object

code

required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string

statement

required

Index of the statement at fault; -1 for the document as a whole.

integer

>= -1

detail

required

string

action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string

errors

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.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object

field

required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string

message

required

string

details

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

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}