Metal Servers and provider integration
A Metal Server is the Atlas app's record for a physical host running Metal. Operators manage hosts through Desk. The tenant API does not expose host administration.
Register and prepare a host
Atlas Settings selects one provider per region. Its adapter validates credentials, supplies the host catalog, and performs remote actions. Adapters can create a host or register one prepared manually.
| Record | Purpose |
|---|---|
| Metal Server | Provider identity, addresses, setup progress, and status. |
| Metal Server Size and Image | Provider catalog for new hosts. |
| Metal Server Usage | Capacity reports for placement. |
| SSH Task | Host command and result. |
Atlas commits a Pending record before contacting the provider. The stable record name lets retries find the same remote host.
Setup prepares provider resources, SSH, networking, WireGuard, and Metal. It saves completed phases in MariaDB and marks the host Running only after completion. See the provisioning sequence.
Retry setup
On failure, read the phase in the Error Log. Correct the cause, then use Setup Metal Server. Keep the provider identity so the retry can reuse the host.
Setup runs as Administrator. Setup and daemon upgrade share a per-server job lock, so they cannot run together.
Desk actions
Each method checks permissions and local state before delegating long work.
| Area | Methods |
|---|---|
| Setup | setup_server, configure_wireguard, install_metald, upgrade_metald |
| Power | reboot_server, poweroff_server, poweron_server |
| Inventory | ping_server, sync_disks, sync_state |
| Removal | archive_server |
Upgrade metald
Check console preservation before restarting Metal. An empty systemd descriptor store means every running VM on the host stops.
| Action | Behavior |
|---|---|
install_metald | Writes configuration and units. Installs missing binaries. Does not replace a running daemon. |
upgrade_metald | Downloads the build from Atlas Settings, saves /usr/bin/metald.previous, installs the build, and restarts metal.service. |
The upgrade script reports the descriptor count before restart. It checks the new service five times. On failure, it restores the previous binary, restarts the service, and reports the error.
If it reports an old unit, run Re-configure Metald. This adds FileDescriptorStorePreserve=yes, which the host systemd version must support.
Capacity and state reports
Periodic host sync sends policy and receives capacity and VM state. Atlas saves usage samples and a state cache.
A Running host still needs a recent sample for placement.
Limits and recovery
Provider adapters support different power and address actions. Unsupported optional actions fail explicitly.
Setup needs valid provider credentials, root SSH, network access, and a suitable storage device. To add an adapter, follow the provider guide. Provider methods return remote resource data. Atlas owns Frappe record changes.
Source code and tests
- Metal Server module specification maps the host records and jobs.
- Provider contract and registry define the integration boundary.
- Host provisioner owns the phase order and commits.
- Host installation installs Metal and host services.
- Host sync stores capacity and state reports.
- Metal Server tests check record lifecycle behavior.