Skip to main content
An image is the disk an instance’s boot volume is cloned from. Images are regional resources in the compute service. Manage instance login through SSH access with IAM.

Names are movable tags

How debian-13 and debian-13:20260807 differ, and when the tag moves under you.

Importing

Presigned URL in, background conversion, and what the status column tells you.

What the listing shows

Why a build you published yesterday is missing, and the flag that brings it back.

​
Images

​
Your images and the platform catalog

GET /v1/images returns only images owned by your selected account. Your images remain private to that account; publishing them to other accounts is not supported. Images have no visibility field or filter. Use GET /v1/image-catalog to choose an image for a new instance. Its categories array groups images under platform and account. Each entry describes the current active build of one image name and architecture, with its ID, CRN, OS, minimum disk and memory sizes, and end-of-life date when known. The catalog omits tags and operational metadata. It accepts name, os and architecture filters and paginates with limit and marker across both categories. Platform images are maintained OS images available to every account. Their CRNs belong to the platform account (crn:compute:<region>:platform:image/<name>/architecture/<arch>/version/<version>). Selecting a platform image does not give you permission to change or delete it.

​
A name is a tag, a version is a build

Every image row has a name and a version, and they do different jobs.

name

A movable tag, shared by every build behind it. debian-13 points at whichever build is current for its (name, architecture).

version

Identifies one build within that name, and must be unique there. Omit it on import and the server stamps a UTC timestamp, so every build is addressable whether or not you labelled one.
That gives three ways to name an image at launch, and the choice is a choice about reproducibility: is_current on the image says whether it is the name’s current target. Older active versions stay bootable by id and by name:version. Promotion moves a pointer; withdrawal or deletion makes a build unavailable for new launches.
Publishing a version the name already carries returns 409. It does not replace the existing build or move the current pointer. Publish a new version; do not delete the existing build to make a retry overwrite it.

​
Importing an image

No image bytes flow through the API. You upload the disk to a bucket you control — the Basaltic object store, S3, MinIO, anything — with a real multipart S3 client, then hand over a presigned GET URL. Import an AMD64 (x86-64) Linux image. The architecture field accepts only amd64, which is also its default; ARM images are not supported. Set os to almalinux, alpine, arch, centos, debian, fedora, opensuse, rhel, rocky or ubuntu. For another Linux distribution, use linux (the default). Keep the release in the separate os_version field. Unsupported architecture or OS values return 400 INVALID_INPUT before an import is created.
1

Register the import

Go to Compute → Images in the target region and choose Import image. Enter Name and an optional Version. Paste the presigned HTTPS GET URL into Source URL. Choose an Operating system and optionally enter OS version. Choose Other / generic Linux for another distribution. Architecture is fixed to AMD64 (x86-64). Leave Version blank for a server-generated UTC timestamp.Choose Import image. Import accepted reports the returned importing status and opens the image page. The image is private to your account. Once active, it becomes the current build for its name and architecture, changing future launches that use the bare name.
The response is 202 with status: "importing". The platform automatically detects qcow2, raw, vmdk, vhd, vhdx and vdi from the downloaded disk and converts it to a raw base. You do not supply a format.
2

Wait for the fetch and conversion

A worker fetches the URL once, converts the disk and imports it. The URL is not retained afterwards, so it only has to stay valid long enough to be read.
3

Poll until active

In the console, use Refresh on the image page or Compute → Images. The Status column shows the latest import attempt’s error while retrying, or the terminal failure when the status reaches error. The same error is visible on the image page.Through the API:
active means bootable, and size_bytes is filled in from what was actually written. error means the import gave up; read faults for the reason.
source_url must be https, and must not resolve to a private address. Loopback, RFC 1918 and ULA private ranges, link-local and metadata addresses are all refused — on the original URL and again on every redirect, against the address it actually resolves to. A bucket reachable only inside your VPC cannot be imported from; presign from something publicly resolvable.
An entry in faults does not mean the import has stopped. Each failed attempt of the same code refreshes that row and increments occurrences rather than adding another, and the import is retried. The row reaching error is what says nothing further will be attempted.

​
Publishing without switching the tag

current defaults to true: a completed import becomes the name’s current version and future launches of that bare name boot the new bits. Send "current": false to stage a build without switching, then promote it later:
Promotion is atomic — whatever else was current for that (name, architecture) is demoted in the same operation. The same call is how you roll back: point the name at the older build and launches follow it immediately.
The switch happens when the import completes, not when it is accepted. A new build is importing for as long as the conversion takes, and the tag keeps pointing at the previous build for all of it — so publishing over a name in use never leaves it resolving to something that cannot boot.Only an active image can be made current; asking to promote one that is still importing is a 400.
Promotion and rollback are API only. An image’s page in the console edits its Description, Tags and Attributes when owned by the selected account and not deleting. Name is read-only. There is no console control that moves the tag. The listing shows you where the tag points, as a current badge on the build it resolves to, but moving it is this PATCH.

​
What List images returns

GET /v1/images lists your account’s current builds and images that need attention. One name normally contributes one entry; use the catalog endpoint above to include platform images. An active build drops out when a newer build holds its name. Withdrawn builds are also excluded by default:
Whatever its age. These are rows you have to deal with — an import you are waiting on, or one that failed and is still holding an image slot until you delete it.
“Not current” is the wrong test on its own. A version you staged deliberately, and a version you rolled back from, are both not current and both still yours to act on. Only being superseded by something newer takes a build out of the listing.
Use status=withdrawn or all_versions=true to inspect withdrawn images. They remain readable by ID and retain their data, but cannot be launched. In the console, choose Withdrawn on Compute → Images; Catalog restores the default view. Deleting images remain readable until cleanup finishes.
Pass all_versions=true for a tag’s whole history, including withdrawn builds. Results are ordered by name, and paginate through meta.marker like every other listing. The other filters are os, architecture, status and name. The name filter is an exact match.

​
End of life

eol_date records the day an OS release stops receiving free security updates for a default install. Absent means nobody has recorded one, which is not the same as supported indefinitely. Omit eol_date on a new build and it inherits the date the name’s current version carries, so republishing a tag cannot quietly stop tracking its release. An explicit null on PATCH clears it; omitting the field leaves it alone.
Platform images are withdrawn from the catalog a grace period after their eol_date. They stay bootable by id until then, and the date is published well ahead of it so you can plan the move.After withdrawal, resolving the bare name fails with a message naming the release and the date it ended — so a launch that suddenly cannot find some-distro-11 tells you why, rather than looking like a typo. Anything pinning name:version or an id of a withdrawn platform image also stops launching. You can still inspect the withdrawn image by ID.
Withdrawn images carry withdrawal_reason. end_of_life identifies a platform release withdrawal; inspect eol_date for its date. legacy means the image was already withdrawn and its original reason is unknown. The console shows this explanation beside the status. An eol_date on your own image is stored and shown. Automatic end-of-life withdrawal applies only to platform images; it does not withdraw your own images.

​
Deleting an image

Open the image from Compute → Images and choose Delete. The confirmation requires the image name. Remove references from instances and instance pools first. After Image deletion accepted, use Refresh to follow cleanup until the page shows Image not found.Edit and delete controls require ownership by the selected account and disappear while deleting. Platform catalog images are read-only outside the platform account.
An unused image returns 202 with the image in status: "deleting". Cleanup runs asynchronously. GET /v1/images/{image_id} returns that resource until cleanup finishes, then returns 404. A deleting image cannot be launched or changed. A repeated DELETE returns 404, including while cleanup is running. If instances or instance pools still reference the image, deletion returns 409 and leaves it unchanged. The server message includes both counts, including zero: image is in use by 2 instances and 0 pools. Remove those references before retrying. Withdrawn images have the same checks. An image already marked for deletion can still be retained for existing instances or instance pools. In that case, its owner’s list and detail responses include deletion_retention with reason: "in_use", instances and instance_pools counts. The console explains which references are holding the image. This means backing data is being preserved for those resources; it does not mean the deletion worker has stalled. Cleanup can finish after the references are removed. The field is omitted when no such references remain.
Superseded builds of your own images are never reclaimed for you. Every build you publish holds an images slot and its bytes against image_storage_gb until you delete it — so a pipeline that publishes on every commit needs a deletion step, or the quota becomes the deletion step.
A withdrawn image retains its data until its owning account deletes it. Reading a public platform image does not grant permission to delete it.

​
Sizes

​
enforced floor
The smallest boot volume that can hold the image. Defaults at import to the image’s virtual size rounded up. A launch or reinstall asking for less is refused.
​
recorded, not enforced
What the image is documented to need. It is stored and returned for you to read; nothing stops an instance booting on a flavor below it.

​
Troubleshooting

Check whether a newer build holds the same name. The default listing shows one entry per tag, and drops builds a newer one has superseded. Add ?all_versions=true to see the history — the build is still there and bootable by name:version or by id if its status is active.
A bare name follows the tag, and the tag moves when a new build is published as current. Pin name:version or an id in anything that has to be reproducible; keep the bare name for “always the latest”.
Two causes. A platform release past end of life has been withdrawn — the error names the release and the date. Or the name has no current version, which happens after a PATCH with current: false on the only current build: the tag then points at nothing, though active builds behind it still launch by name:version. Promote one to fix it.
Read faults — a failed attempt records the reason on the row while retrying, and a repeated failure of the same code bumps occurrences rather than adding a row. The usual causes are a presigned URL that expired before the fetch, a disk whose format cannot be detected or is unsupported, a disk that references an external backing file, or a host that resolves to a private address and is refused. Detection and backing-file checks happen asynchronously after the download; acceptance does not mean the disk is valid.Note that an import which finishes but exceeds your image_storage_gb quota is refused and not retried: rebuilding the same bytes would cost a full download and conversion to reach the same answer.
That name already carries that version. A name is shared by every build behind it on purpose, so publish under a new version rather than a new name.
That is the design. Only the platform catalog crosses accounts; visibility: "public" on your own image does not share it, and an image id belonging to another account answers 404 rather than 403, so the API never confirms it exists.

​
Next

Launching instances

Flavors, boot volumes, cloud-init and the instance lifecycle.

Instance pools

Where an image reference is resolved once, at create, and every replica boots the same build.