Upload a disk image (qcow2 or raw) into the image catalog.
curl --request POST \ --url 'https://stratum.example.com/v1/images/upload?name=example&format=qcow2&architecture=amd64&scope=global' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/octet-stream' \ --data binaryAn operator’s own image, uploaded. The body is the disk image
itself (Content-Type: application/octet-stream, streamed; a
Content-Length is recommended but not required), and its metadata are
the query parameters. Install-scope; gates on compute:ImportImage, like
the URL import. The image is global or region scoped and owned by
p-system, so p-system’s compute.images.count quota applies (429).
Checked before the body is read: the name (and that no live image has
it), the scope, the storage class, the quota, and a Content-Length over
the limit. Then the bytes are staged on the control plane that received
them, their sha256 computed (and compared with sha256 when given), and
qemu-img info validates them: a qcow2 or raw disk (the format is read
from the bytes; format, when given, must match), with no backing file,
no external data file, not encrypted, and a virtual size within the
limit. A refused upload records nothing and keeps nothing.
Returns 202 with the image pending, sourceUploadNode naming the node
that holds the staged bytes. That node’s storage worker imports it into
the class like any import (pending -> downloading -> importing ->
active; qcow2 is converted to raw) and then removes the staged copy.
A failed import ends in error: delete the image and upload it again.
In a per-node class (lvm-thin) only the receiving node gets a copy.
Limits: 64 GiB uploaded (STRATUM_STORAGE_IMAGE_UPLOAD_MAX_BYTES), 4 TiB
virtual size.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”The image’s name, unique among live global and region images.
The disk’s format. Left out, it is read from the bytes; given, it must match them.
The upload’s expected sha256 (hex). A mismatch refuses it (400 CHECKSUM_MISMATCH).
Required when scope is region.
The storage class the image is imported into. Left out, the default class.
Request Bodyrequired
Section titled “Request Bodyrequired”Responses
Section titled “Responses”Received and validated; the image is pending until its import finishes.
object
P-system for global; owning project for scoped
arn:stratum:compute:<region>:<owner>:image/<id>,
the key a resource policy shares the image under
(PUT /v1/iam/resource-policies?resourceArn=).
The project that owns the image (always equal to
projectId): whose quota it counts against and whose editors may
share, publish and delete it.
Who may launch the image. private: the owner
project only. shared: plus every principal a resource policy on
the image ARN permits compute:UseImage (a project-kind principal
is what share writes). public: every project on the install.
Independent of scope, which is storage placement.
The requesting project’s relation to the image: self (owned),
system (the operator’s public catalog), shared (granted by a
resource policy), public (another project’s public image). Filled
on the project-scoped reads; absent on the admin surface.
The projects a resource policy on the image ARN grants
compute:UseImage — present on the OWNER’s reads only; a grantee
does not see who else was granted. Derived from the policy.
The source format the image was imported from (stored raw).
The storage classes (by name) a launch of this image may name as
rootStorageClass, or create-volume as storageClass:
active, on the image’s storage driver, and, for a driver whose clones
are pool-local (lvm-thin), on the pool the image is staged in. Any
other class is refused with 409 IMAGE_POOL_MISMATCH. The server
derives it from the rule it enforces, so a client offers this list
rather than recomputing it. Omitting the class always launches on the
image’s own storageClass. Absent when no class can be named or the
classes could not be read.
Where VMs launched from the image can run. A shared storage
class (Ceph) holds one copy every node reads: scope is all-nodes and
nodes is absent. A per-node class (lvm-thin) holds a copy per node, staged
from the image’s source: scope is nodes and nodes lists every node with
a staging row, so a VM runs only on the nodes in state ready. An image
uploaded through the API into a per-node class has its bytes only on the node
that received them (sourceUploadNode); every other node reports error
with the reason. Import it from a URL, or upload it into a shared class, to
run it everywhere. Absent while the image is not usable (not yet active)
or when the nodes could not be read.
object
Per-node staging state, ordered by node id; only when scope is nodes.
One node’s staging readiness for an image.
object
Per-node staging lifecycle. ready means a VM can clone its root volume from the local base LV here.
Failure detail when state is error; absent otherwise.
Size of the staged base LV in bytes; absent until known.
The bucket a bucket import read from.
The object key a bucket import read.
An uploaded image (POST /v1/images/upload): the node whose
control plane received the bytes. They stay staged there until the
import has written them into the storage class.
Every export job requested on the image.
One export job on an image.
object
Hex-encoded SHA256 of the uploaded object (succeeded only).
Why the job failed (failed only).
The instance a create-image was taken from.
The image that instance booted (lineage).
How a create-from-instance snapshot was taken:
the instance was stopped, the guest agent quiesced its
filesystems, or neither answered and the image is crash-consistent.
Absent on imported and promoted images.
The volumes the image carries; device 0 is the root snapshot, higher indexes are data volumes cloned at launch. Empty for single-volume images.
One volume an image carries. Device 0 is the root
(also sourceSnapshotId); higher indexes are data volumes cloned at
launch. A launch may override sizeBytes upward.
object
Where a create-from-instance is while the image
is pending: requested → stopping | freezing → snapshotting → thawing | starting → promoting → done, or failed (the image is
then error with stateReason). Absent on every other image.
Human-readable cause. Set when state is error, and
while deleting when the delete is BLOCKED: a volume
still CoW-cloned from this image, the backing store still held
open, or a transient backend error. A blocked delete is not a
failure — the image stays deleting and the worker re-attempts
it about once a minute until the blocker clears (a clone you
delete, a watcher that goes); nothing needs re-issuing. Cleared on
any other transition.
Read this before acting on an image that is not gone yet: it names the volume to delete, or tells you an operator is needed.
When the image became public: stamped by publish
and by the operator catalog’s activation, cleared by unpublish. A
private or shared image has none — this is a visibility stamp, not
“became available” (createdAt / state say that).
Set while the image is disabled.
The last launch from the image, stamped at most once an hour.
A scheduled deprecation not yet applied.
What references the image, on the owner’s reads:
the launch templates whose $Default or $Latest version names it.
A deregister without force is refused while this is non-empty.
object
AWS-shape resource tags. Freeform UTF-8 keys (1-128 bytes, no
leading/trailing whitespace) mapped to freeform UTF-8 values
(0-256 bytes). Max 50 tags per resource. Reserved prefixes
(stratum.dev/, stratum.platform_health., stratum:,
aws:) return 400 RESERVED_NAMESPACE on customer input.
PATCH replaces the whole map..
object
Example
{ "visibility": "private", "owner": "self", "format": "qcow2", "architecture": "amd64", "driver": "lvm-thin", "availability": { "scope": "all-nodes", "nodes": [ { "nodeId": "n-msst0001", "state": "pending" } ] }, "scope": "global", "exports": [ { "format": "qcow2", "state": "pending" } ], "consistency": "stopped", "createPhase": "requested", "state": "pending"}INVALID_INPUT (name, scope, region, storage class, format value),
CHECKSUM_MISMATCH, or INVALID_IMAGE: qemu-img cannot read it, it
is not qcow2 or raw (or not the format given), it names a backing
file or an external data file, or it is encrypted.
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" } ]}Authenticated but not authorized.
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" } ]}IMAGE_TOO_LARGE: the upload, or the virtual size it describes, is over the limit.
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" } ]}UNSUPPORTED_MEDIA_TYPE: the body is not application/octet-stream.
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" } ]}QUOTA_EXCEEDED: p-system’s compute.images.count is at its limit.
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" } ]}INSUFFICIENT_STORAGE: the staging filesystem cannot hold an upload of that length.
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" } ]}