host: controller synchronization and capacity

For Go code, follow the repository Go anti-pattern rules.

Metal specification · Behavior: host sync

Purpose

The host package applies the controller-owned sets: WireGuard peers, image policies, privileged VM addresses, and WireGuard gateway return routes. Each complete set replaces the previous one.

Types

Type	Responsibility
Service	Applies desired host state, then reports the sync result.
DesiredState	The 3 controller-owned sets, each complete.
SyncResult	What one sync returns: capacity and VM states.
Capacity	Host capacity for placement.
PrivilegedMesh, WireGuardManager, ImagePolicyStore, VirtualMachineSource, StorageCapacitySource	Injected services.

• Service holds no state. Each injected service owns the state it applies.
• The mesh service is nil when Atlas WG Mesh is disabled.
• Dependencies.Compatibility holds the immutable facts that metald captures at startup. Each SyncResult returns the same optional report. Atlas owns compatibility decisions. See host sync.

Synchronize

POST /v1/sync runs these steps in order and stops at the first error:

1. Apply the privileged VM addresses.
2. Apply the WireGuard peers.
3. Set the image policies.
4. Set the WireGuard gateway return routes. vm.Manager stores them and adds them to each VM with is_accessible_via_wireguard_gateway. A VM route with the same destination wins.
5. Wake the reconcilers.
6. List the VM state once.
7. Return the SyncResult.

Wake must follow the writes, so reconcilers act on the new policies at once.

Capacity

Resource	Source
CPU total	Host CPU count × 1000 millicores.
CPU available	Total minus VM cpu_millicores and the reserve, floored at zero.
Memory available	The smaller of MemAvailable from /proc/meminfo and total memory minus the reserve and the memory_mib of each VM that runs, pauses or boots. A sleeping VM holds no memory.
Storage	StorageCapacitySource, minus the reserved percent of the pool.

• The [capacity] section of metald.toml sets the Reserve. Each missing key is 0. install-metald.sh writes 18432 MiB of memory (the ZFS ARC maximum and the host system), 2000 millicores and 10% of the pool. On the host that runs the Atlas VM, it adds the memory and CPU of that VM.

• CPU is for visibility only. No admission check uses it.

• VirtualMachineSource skips a VM that has only one of its two records.

Virtual machine states

SyncResult.VirtualMachineStates maps each VM ID to its last observed state. It reuses the capacity List call, which reads stored records, not the runtime.

Related

• internal/api/SPEC.md owns the sync request and response shapes.
• internal/network/SPEC.md owns WireGuard peers and the privileged mesh.
• internal/storage/SPEC.md owns image policies and pool capacity.