List the images the project can launch.
curl --request GET \ --url 'https://stratum.example.com/v1/projects/example/compute/images?owner=self&sort=lastLaunchedAt&scope=global' \ --header 'Authorization: Bearer <token>'The project’s own images, the operator’s public
catalog, every public image, and the images shared with the project
through a resource policy on their ARN. Each item carries owner
(self | system | shared | public); the project’s own items carry
sharedWith. Gated on compute:ListImages (storage:ListImages
is an alias for one era).
owner= narrows to one relation; name= is an exact match;
distribution= matches osDistribution case-insensitively; tag=
is key=value or key for presence; include-deprecated=true
shows images with deprecatedAt set (hidden by default). scope=
keeps the pre- storage-placement filter.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”key=value, or key for presence.
lastLaunchedAt orders most recently launched first (never launched last); default is by name.
Responses
Section titled “Responses”Images.
object
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
True when the server had more rows than it returned. The response is a valid prefix of the result, not the whole of it.
Without this flag a client at the server’s row ceiling receives a full
page and no nextPageToken, which means “this is
the complete set” — so data it never saw would be indistinguishable
from data that does not exist.
It does not imply a cursor exists. These queries do not all sort on a total order, so a resumable token cannot be minted for them yet. The remedy is to narrow the request (a filter, or a tighter scope), not to page.
Example
{ "items": [ { "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" } ]}