VM images and artifact storage
The Atlas app owns image records and published artifacts. Metal caches them 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 kernel, root filesystem, architecture, sizes, and SHA-256 digests. Only an enabled, Available image can create a VM.
System images
The Ubuntu builder stores a kernel and root filesystem, calculates their digests, and creates or updates an Available System image.
An unchanged build keeps its version. A changed build increases the version after both artifacts are stored.
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. It does not repair the disk. The guest disk incident explains why this guard was added.
Artifact storage
The artifact_storage field selects the artifact location:
| Value | Location | Download URL |
|---|---|---|
Object Storage | Atlas Settings bucket, under vm-images/sha256/<digest>/<name> | 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_base_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 repeats the search every 15 minutes, including failed migrations. Migrate to Object Storage starts one immediately.
For each image, the job:
- Uploads both artifacts under content-addressed keys and compares sizes.
- Saves the keys and changes
artifact_storage. - Deletes the site Files.
A downloadable copy remains 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 and kernel on Metal. Metal's UUIDv7 snapshot ID becomes the Atlas image record name.
Atlas saves multipart upload IDs before it starts the transfer. It checks hashes and sizes before publication.
On failure: Atlas keeps the source host, snapshot ID, object keys, and upload IDs. Retry Transfer reuses them and the same image record. Signed URLs stay out of 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 the normal Machine image transfer and its retry path. A transfer can also fail before upload or during completion. Retirement changes an Available or Failed image to Archived or Deleting as described below.
Retirement and deletion
Retire an Available or Failed image to disable new use immediately. Retiring an already Deleting or Archived image changes nothing.
| Image | Result |
|---|---|
| System image | Archived. Shared artifacts remain. |
| Unused Machine image | Deleting. A job removes objects, Metal staging, and the record. |
| Machine image still in use | Archived. Changes to Deleting after its last VM is deleted. |
Image-use checks read the last-reported Virtual Machine State cache. Cleanup failures keep Deleting, record the error, and retry 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 exact image and VM shape. It stays on its host. If a shared warm artifact cannot be used, boot falls back to a cold start.
Limits and recovery
Check artifact URL access and free host storage before retrying a transfer. See Metal storage for local staging and cleanup, and the Atlas API for image operations.
Source code and tests
- Image DocType owns image metadata and visibility.
- System image builder publishes base artifacts.
- 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.