Create an image from a running or stopped instance (async).
curl --request POST \ --url https://stratum.example.com/v1/projects/example/compute/instances/example/actions/create-image \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "displayName": "example", "description": "example", "noReboot": false, "blockDeviceMappings": [ { "deviceIndex": 1, "volumeId": "example", "deleteOnTermination": true } ], "tags": { "additionalProperty": "example" } }'. Gated on compute:CreateImage (the project) and
compute:DescribeInstance (the instance). Counts against
compute.images.count. The instance must be running or stopped
(409 otherwise); a mapped volume that is not attached to the instance
fails the image (state: error with the reason), never the request.
Poll the image: createPhase walks requested → stopping | freezing → snapshotting → thawing | starting → promoting → done.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”Create an image from an instance in one verb. The
root volume is always captured; blockDeviceMappings names data
volumes (attached to the instance) to capture alongside it. Returns 202
with the image pending and createPhase: requested; the images
reconciler drives it (stop or freeze → snapshots → thaw or start →
promote) and the image reaches active with consistency set.
object
false (AWS semantics): the instance is gracefully stopped, the
snapshots are taken, and it is started again — consistency: stopped. true: the guest agent is asked to freeze its filesystems
while the snapshots are taken (quiesced); if it does not answer
the snapshots are taken anyway and the image says
consistency: crash. An instance that is already stopped is
captured as it is, without a start.
Data volumes to capture; each must be attached to the instance.
object
Recorded on the image; applies to the volume a launch clones.
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
Responses
Section titled “Responses”Accepted; the image is pending.
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"}Bad request.
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" } ]}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" } ]}Request rate limit exceeded. The API-boundary throttle caps request throughput per principal and per project; code is RATE_LIMITED (distinct from the quota engine’s QUOTA_EXCEEDED). The Retry-After header carries the seconds to wait. Applies to any authenticated endpoint — it is enforced by middleware, not per-path.
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" } ]}Headers
Section titled “Headers”Seconds to wait before retrying.