Skip to main content
Fleet Manager is designed as a control plane for hardware lifecycle workflows. The API is the operator entrypoint, while workflow workers and background agents do the long-running and integration-heavy work outside the request path.

​
Core Building Blocks

  • Fleet Manager API provides the main control plane and serves data from Fleet Manager’s own database
  • Workflow Agent synchronises workflow intent and Temporal status back into Fleet Manager
  • NetBox Agent synchronises inventory and site data from NetBox
  • Temporal Workers run durable workflow and activity logic
  • PostgreSQL stores Fleet Manager’s queryable state and API-facing data model

​
Why Fleet Manager Uses Agents

Fleet Manager does not want API endpoints to fan out directly to external systems for every request. The main architectural reason is query shape and scale. For example, showing a page of jobs should not require one list call plus one live status call per job against Temporal. Instead:
  • agents poll or otherwise reconcile external systems in the background
  • Fleet Manager stores the synchronised state in its own database
  • the API serves operators from that local state
This avoids N+1 request patterns, reduces coupling to external APIs, and keeps the UI usable even when an upstream system is degraded.

​
Workflow Model

Fleet Manager’s long-running orchestration is centred on Temporal. That choice was driven by the need for:
  • durable workflows that survive restarts
  • retryable and heartbeated activities for unreliable infrastructure
  • cancellation and manual-intervention points
  • long-running execution for multi-stage enrolment and burn-in jobs
The workflow platform is intended to handle both current provisioning flows and future day-2 operations such as remediation, quarantine, or hardware triage workflows.

​
Hub and Satellite Topology

Fleet Manager is deployed as a hub plus one or more satellites.
  • The hub hosts the API and presents a single global view of the fleet
  • Each satellite runs site-local workflow workers and other components close to the hardware and credentials they need
  • Satellites use their own vault selection, PKI material, and deployment-specific configuration
This keeps trust boundaries explicit and lets sites be added or rotated independently.

​
External Systems

A typical deployment integrates with:
  • NetBox as the inventory source of truth
  • OpenStack services such as Ironic, Nova, and Placement
  • DHCP infrastructure used during provisioning
  • 1Password and related secret-management workflows
  • SLURM for hardware-test execution
  • Prometheus and Grafana for metrics and logs
For the full map of device status axes, conditions, and per-integration write paths, see Device State Machines.

​
Development Implications

Some architectural rules follow directly from this design:
  • long-running work should not happen inside API requests
  • external I/O belongs in activities or agents, not in Temporal workflow definitions
  • Fleet Manager’s API layer should depend on its own typed models rather than ad hoc external payloads
  • site-specific configuration belongs with the deployment, not in code-time branching