VM images and artifact storage
Atlas owns image records and artifacts. Metal caches the artifacts on hosts and creates VM disks. See the transfer flow for the sequence.
| Image type | Access |
|---|---|
| System | Shared with every tenant. |
| Machine | Owned by the source VM's tenant. |
An image records its root filesystem, architecture, sizes, and SHA-256 digests, and links one kernel record. Only an enabled, Available image can create a VM.
Kernels
A Virtual Machine Kernel record stores one kernel under its SHA-256 value. Every image with that kernel links the same record, so Atlas stores and uploads each kernel once. Atlas deletes a kernel record and its stored file when no image links to it.
System images
The Ubuntu builder publishes a kernel and root filesystem as a new Available System image. Each build gets a new record and its own rootfs path. A build with an unchanged kernel reuses its kernel record.
Each Ubuntu image build uses the latest Ubuntu cloud image release and the newest kernel that Ubuntu supports for that release: the HWE (hardware enablement) kernel for 22.04 and 24.04, and the generic kernel for 26.04. The rescue image uses the 24.04 steps. The build log shows the download URLs.
The builder checks earlier Available images with the same title, architecture, and purpose tag. If one has the same digests, the build changes nothing.
After base image publication, the builder retires the earlier base images. Rescue builds keep earlier images. See rescue mode.
Atlas protects each new System image from termination. The base image builder removes this protection from earlier base images before it retires them.
Guest disk errors
New Ubuntu System images set ext4 to remount the root filesystem read-only when it detects an error. This stops further writes to a damaged filesystem.
The remount does not repair the disk. See the guest disk incident for the reason behind this setting.
Artifact storage
The artifact_storage field selects the artifact location:
| Value | Location | Download URL |
|---|---|---|
Object Storage | Atlas Settings bucket: the rootfs under images/<image ID>/, the kernel under kernels/<SHA-256> | Signed. Valid for 24 hours. |
Site File | Public site File under /files/ | Public. No expiry. |
Bootstrap without object storage
Build the first System image with --storage site-file. Set atlas_internal_url to an address the host can reach.
Site Files are public, so only System images can use them. The tenant download route refuses Site File images.
Move artifacts to object storage
Saving object-storage settings queues migration of Available Site File images. A job checks again every 15 minutes, including images whose earlier migration failed.
Use Migrate to Object Storage to start one migration immediately.
For each image, the job:
- Uploads the rootfs under a key owned by the image, and the kernel under
kernels/<SHA-256>when it is not in object storage yet. It compares sizes. - Saves the keys and changes
artifact_storage. - Keeps the site Files for six hours so hosts can finish earlier downloads, then deletes them.
Hosts have a downloadable copy at each step. The immutable_reference uses architecture and digests, so hosts keep their existing cache.
Machine images
Select Create Machine Image to stage the VM disk on Metal. Metal's UUIDv7 snapshot ID becomes the image record name. The image links the kernel of its source VM, so Metal uploads only the disk.
Atlas saves multipart upload IDs before it starts the transfer. It checks hashes and sizes before publication.
If a transfer fails, Atlas keeps the source host, snapshot ID, object keys, and upload IDs. Retry Transfer uses the same image record and upload IDs.
Atlas does not write signed URLs to logs.
Listing
GET /api/atlas/images: enabled tenant images and enabled System images. Filter withimage_type=systemorimage_type=machine.GET /api/atlas/images/<image ID>: also returns disabled images so clients can follow retirement.
Image status
The diagram shows a Machine image transfer and its retry path. A transfer can also fail before upload or during completion.
A timeout or a 5xx answer from the source host does not fail the transfer. Atlas shows the error on the image, keeps its status, and the pending-transfer job tries again.
Retirement changes an Available or Failed image to Archived.
Retirement and deletion
Retire an Available or Failed image to stop new use immediately. Retiring an image that is already Deleting or Archived changes nothing.
Termination protection blocks retirement for both System and Machine images.
Atlas keeps a retired image's objects or public site files for six hours. This gives hosts time to finish downloads that started before retirement.
A migrated image also keeps its old site files until the separate migration deadline ends.
The image stays Archived with its rootfs and kernel while any VM record names it. A host can prune its cached copy, so a VM that starts, restarts, or migrates must still be able to download the image.
After the deadline and the last VM record, Atlas changes the image to Deleting, deletes the remote rootfs and Metal staging, and removes the record.
Atlas records a cleanup failure and retries every 30 seconds.
Cached and warm artifacts
Host sync requests caching for enabled Available images with cache_image.
A warm artifact contains disk, memory, and Firecracker state for one image and VM shape. It stays on its host.
If a shared warm artifact cannot be used, the VM starts without it.
Limits and recovery
Check artifact URL access and free host storage before you retry a transfer.
See Metal storage for local staging and cleanup. See the Atlas API for image operations.
Source code and tests
- Image DocType owns image metadata and visibility.
- System image builder publishes base and rescue artifacts with separate purpose tags.
- Rescue image recipe builds the independent repair image. See rescue operation.
- Ubuntu image script builds the guest root filesystem and sets its error behavior.
- Machine image transfer owns snapshot progress.
- Storage migration moves bootstrap files to object storage.
- Image deletion retires and reclaims artifacts.
- Object storage client owns signed URLs and object operations.