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.
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.
- Draft and termination reconciliation settles uncertain outcomes.
- Reported state cache stores host sync results.
- VM service tests check the create and retry contract.