Code Map

Choria Provisioner is a single Go binary, about 2,400 lines across four packages. It finds Choria Servers that have no configuration, asks a site-supplied helper what their configuration should be, writes it over Choria RPC, and restarts them.

Snapshot

Generated 2026-08-19 against commit aca2b62 on branch main, with a clean working tree.

The provisioning flow

A freshly installed Choria Server with provisioning enabled connects to the broker’s provisioning collective and answers only the choria_provision agent. Provisioner is a client on that same collective. It finds such a server through broadcast discovery or a lifecycle event and puts it on the work queue. A worker then runs a fixed sequence of RPC calls against that one server: fetch its JWT, fetch its key material, fetch its inventory, ask the helper for a configuration, send the configuration back, and restart it. The helper handles certificate authorities, naming schemes, fact sources, and policy decisions. It is a program in any language that reads JSON on standard input and writes JSON on standard output.

Choria Serversprovisioning modeno configuration yetChoria Brokerprovisioning collectivelifecycle eventsProvisionerdiscover, queue, workN worker goroutinesstartup eventdiscoverRPCconfigure, restartHelperany language, JSON I/Ohost JSON outconfig JSON backCA or Issuerreached by the helper
Discovery and events both reach the same worker pool. Environment-specific work happens in the helper.

A startup log

A Provisioner that wins the election logs its discovery interval and worker count, followed by one line for each host admitted and one for each RPC issued:

INFO Choria Provisioner starting using configuration file /etc/choria-provisioner/choria-provisioner.yaml. Discovery interval 1m using 4 workers INFO Starting leader election against 'provisioner' WARN Became leader after winning election INFO Triggered a discovery after becoming leader INFO Looking for provisionable hosts INFO Adding n1.example.net to the provision list after discovering it INFO Adding n2.example.net to the provision list after receiving an event INFO Provisioning n1.example.net INFO Fetching JWT -> Fetching Inventory -> Configuring node -> Restarting node INFO Provisioned n1.example.net

Pages in this map

  • Architecture: Package layering, the import direction, and the boundaries that put site-specific logic in the helper program.
  • Discovery and the work queue: How a server is noticed, admitted to the queue, and picked up by a worker.
  • The provisioning cycle: What Host.Provision does to a server, which steps the feature flags gate, and what the delay flag controls.
  • The helper contract: The JSON exchange between Provisioner and site-specific logic, and how the child process is run.
  • Security and enrollment: JWT verification, the ed25519 challenge, CSR name checks, server token issuance, and how a private key is protected in transit.
  • RPC, retries, and upgrades: The wrapper every Choria call runs through, the per-action retry limits, and how an in-place version upgrade is decided.
  • Pausing and leader election: One boolean gates every outbound action. Only a Choria leader election sets it.
  • Reference and map: The command line flags, every source file and what it holds, the exported metrics, and a glossary.
Next

Architecture covers the package layering. Discovery and the work queue follows a server from first sighting to a worker.