Images and snapshots
Atlas keeps the list of images and stores their files in object storage. Metal downloads images to each host and builds VM disks from them. A snapshot goes the other way: from a VM disk to a new image.
Create and transfer an image
Boot from an image
- Atlas sends the image reference, architecture, sizes, checksums, and download URLs.
- Metal verifies the kernel and root filesystem and imports a base ZFS image.
- Metal clones the base image's ready snapshot for the VM disk.
A reference is immutable on a host: different content under the same reference conflicts. Atlas can request cached images through host sync.
Publish a Machine image
Atlas saves upload IDs before it requests the upload. It saves completed digests before it deletes Metal staging.
An image becomes Available only after Atlas completes the objects and removes staging. Metal finishing the upload is not enough.
Warm artifacts stay local
A warm artifact contains guest memory and matching disk state. Shared warm memory is valid only for a first boot with a fresh disk clone.
A later start cold-boots the VM's existing disk. The staging incident explains this restriction.
Failure and recovery
| Image state | Retry behavior |
|---|---|
Pending, Uploading, Completing, Cleaning | Atlas retries through its pending-job scan. |
Failed | Keeps the error and upload IDs for inspection. The normal scan does not select it. |
Metal preserves staging and upload progress. Correct object-storage access, expired URLs, capacity, or host errors before retry. Keep active staging and never log signed URLs.
Details: Atlas image records, Metal storage, Atlas API, and Metal snapshot API.
Source code and tests
- Atlas image transfer owns image status, upload IDs, and publication.
- Multipart upload service owns object-storage completion.
- Metal image store downloads and verifies bases.
- Metal staging and upload own local snapshot transfer.
- Firecracker start enforces the fresh-disk warm rule.
- Image record tests and Metal machine tests check retry and boot rules.