Atlas VM records
An Atlas VM record identifies a tenant resource and reserves a host. Metal uses the same stable VM ID for host execution and retries.
Create and confirm a record
Atlas commits the record as a draft before it calls Metal. The draft holds the host reservation while Atlas checks an uncertain response. How a VM request works explains when Atlas confirms or removes it.
Change VM resources
Atlas sends complete desired compute, disk, network, metadata, and SSH key values.
SSH key changes use Firecracker metadata and the guest's login command. The VM image does not need to be rebuilt for a key change.
CPU uses cpu_millicores: 1000 equals one core. The range is 100 through 32000, avoiding impractical quotas and respecting Firecracker's 32-vCPU maximum.
Read current VM state
| Data | Source |
|---|---|
| Request, host, image, architecture, tenant, resources | Atlas VM record. |
| Current guest state, routes, host error | Metal, read when document properties need them. |
| VM list state | Virtual Machine State, cached from host sync. |
The cache can be stale after failed sync. Compare Metal's desired and observed generations for operation progress.
Terminate or move a VM
Termination retains the Atlas record while Metal cleans up. Atlas removes it only after Metal confirms absence.
Resize stays on the current host if capacity permits. Otherwise, Atlas reserves a destination and creates a migration record.
Guest metadata
Atlas sends custom metadata as a map of string keys and values. Metal publishes it at latest/meta-data/attributes in Firecracker's microVM Metadata Service (MMDS). A change replaces the complete map.
| Value | Limit |
|---|---|
| Custom metadata | Atlas accepts at most 16 entries and 48 KiB of JSON. |
| Custom metadata key | Metal accepts at most 128 bytes. |
| SSH keys | Metal accepts at most 16 keys, each at most 2 KiB. |
| User data | Metal accepts at most 16 KiB. |
| Hostname | Metal accepts at most 253 bytes. |
| MMDS document | Metal sets the Firecracker MMDS limit to 256 KiB. Metal keeps the base document within 248 KiB and reserves 8 KiB for temporary console keys. |
Metal checks the complete MMDS document before it saves a create, network, SSH key, or metadata change. See SSH key changes for the guest login path.
Open the console
VM read access permits a console request. Open a VM console explains the token, realtime bridge, and two guest modes.
Limits and recovery
Keep an uncertain draft if the host cannot be reached. Check current Metal state before retrying a change. The Atlas list alone is insufficient.
Details: Atlas API and Metal reconciliation.
Source code and tests
- VM DocType owns record actions and virtual fields.
- VM service owns cross-service changes.
- Atlas metadata validation limits custom entries and JSON size.
- Metal metadata builder checks the complete MMDS document.
- Draft and termination reconciliation settles uncertain outcomes.
- Reported state cache stores host sync results.
- VM service tests check the create and retry contract.