Skip to content

reconciler: convergence loops ​

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

Metal specification · overview: Metal overview

Purpose ​

This package schedules convergence work. It owns no VM, image, snapshot, or traffic state.

Types ​

TypeResponsibility
VirtualMachineReconcilerRuns VM reconciliation passes.
NewSleepTransferReconcilerRuns sleep staging, compression, upload, and eviction in a separate eight-worker pool.
NewSleepRestoreReconcilerReconciles sleeping VMs and restores remote artifacts in a separate eight-worker pool.
ImageReconcilerCaches images, prunes unused images, kernels, and staged snapshots.
MigrationReconcilerAdvances each active destination migration.
GuestCheckerPings running guests every minute, so a silent guest counts as unavailable.
passSchedulerRuns a pass at startup, on an interval, and on request.

Pass model ​

  • Each operation has its own timeout.
  • VM operations share a fixed number of slots across passes. A pass starts operations and does not wait for them, so one slow VM does not delay the next pass. A pass skips a VM whose operation still runs.
  • Sleep uploads and restores each use a separate pool of eight workers with the same timeout, backoff, wake, and shutdown behavior. They do not occupy normal VM reconciliation workers or wait for each other's pool.
  • Errors are logged. A later pass retries safe operations.
  • A failing VM waits twice as long after each failure, up to 1 minute. Wake clears the wait.
  • Errors after cancellation are suppressed.

Ownership ​

  • metald owns each goroutine and its context.
  • The VM manager owns every state decision and per-VM lock.

AGPL-3.0