Reference and map

Each table links to the page that explains the area it covers.

Where it lives

The whole repository, from main.go down. ABTaskFile, Rakefile, and packager/ hold the build tooling.

Command line

main.go calls cmd.Run, which builds a fisk application named choria-provisioner. The run command is the default, so choria-provisioner --config ... and choria-provisioner run --config ... are equivalent.

Flag	Command	Required	Default	Effect
`--debug`	Global	No	Off	Forces the Choria log level to `debug`.
`--config`	`run`	Yes	None	Names the Provisioner YAML. Must be an existing file.
`--choria-config`	`run`	No	`choria.UserConfig()`	Names the Choria client configuration. Must be an existing file.
`--pid`	`run`	No	Unset	Writes the PID, and removes the file on exit.

--version prints config.Version, which is 0.0.0 in a plain go build. The release build injects it through -ldflags, mapped in packager/buildspec.yaml to github.com/choria-io/provisioner/config.Version.

Source map

File	Lines	Holds
`main.go`	9	The call to `cmd.Run`.
`cmd/provisioner.go`	130	Flags, both config loads, the Choria framework, `/metrics`, signal handling, and the PID file. Architecture.
`config/config.go`	142	The `Config` struct, `Load`, the defaults, and the validation.
`config/pausable.go`	48	`Pause`, `Resume`, `Flip`, and `Paused`. Pausing and leader election.
`config/stats.go`	18	The `choria_provisioner_paused` gauge.
`hosts/hosts.go`	223	`Process`, the package state, broadcast discovery, `add`, `remove`, and `isCurrent`. Discovery and the work queue.
`hosts/event.go`	82	The connector and the lifecycle startup subscription.
`hosts/provisioner.go`	84	The worker loop and the finisher.
`hosts/election.go`	51	The leader election setup and its two callbacks.
`hosts/stats.go`	66	Nine fleet-level counters and gauges.
`host/host.go`	483	The `Host` struct, `Provision`, JWT and CSR validation, server JWT issuance, and key encryption. The provisioning cycle and Security and enrollment.
`host/rpc.go`	404	`rpcWrapper` and every Choria RPC action. RPC, retries, and upgrades.
`host/helper.go`	131	`ConfigResponse` and the child process. The helper contract.
`host/version.go`	210	The vendored RPM version comparison.
`host/stats.go`	42	Five per-server metrics.
`host/host_test.go`	238	Ginkgo specs for `generateServerJWT`, `validateCSR`, and `encryptPrivateKey`.
`tools.go`	18	Build-tagged `tools` imports that pin the Ginkgo CLI, excluded from normal builds.

Key types

config.Config: config/config.go:25. The parsed YAML plus derived durations, the config file path, and the pause flag. Passed by pointer to every package.
host.Host: host/host.go:29. One server. Five exported fields form the helper's input. The remaining fields hold state that the RPC sequence fills in.
host.ConfigResponse: host/helper.go:23. The helper's reply. Twelve optional fields.
host.Version: host/version.go:21. An RPM epoch, version, and release triple with a Compare method.

Exported metrics

Every metric carries a site label taken from the site configuration key. Three init functions register them, one per package.

Metric	Type	Extra labels	Registered in
`choria_provisioner_paused`	Gauge	None	`config/stats.go`
`choria_provisioner_discovered`	Counter	None	`hosts/stats.go`
`choria_provisioner_event_discovered`	Counter	None	`hosts/stats.go`
`choria_provisioner_discover_cycles`	Counter	None	`hosts/stats.go`
`choria_provisioner_discovery_errors`	Counter	None	`hosts/stats.go`
`choria_provisioner_provision_errors`	Counter	None	`hosts/stats.go`
`choria_provisioner_provisioned`	Counter	None	`hosts/stats.go`
`choria_provisioner_busy_workers`	Gauge	None	`hosts/stats.go`
`choria_provisioner_work_queue_entries`	Gauge	None	`hosts/stats.go`
`choria_provisioner_waiting_nodes`	Gauge	None	`hosts/stats.go`
`choria_provisioner_rpc_time`	Summary	`rpc`	`host/stats.go`
`choria_provisioner_rpc_errors`	Counter	`rpc`	`host/stats.go`
`choria_provisioner_helper_time`	Summary	None	`host/stats.go`
`choria_provisioner_helper_errors`	Counter	None	`host/stats.go`
`choria_provisioner_helper_shutdown_requests`	Counter	None	`host/stats.go`

The rpc label is the agent#action string, for example choria_provision#configure or rpcutil#inventory. Monitoring describes what each metric measures.

Configuration keys

Configuration File gives the full operational description. The following table gives the struct field and the reader for each key.

YAML key	Field	Read by
`workers`	`Workers`	`hosts.Process`, to size the worker pool.
`interval`	`Interval`, `IntervalDuration`	`hosts.Process` for the ticker, `add` for the dedup window, `Provision` for the staleness check.
`helper`	`Helper`	`runHelper`, split with `shellquote`.
`token`	`Token`	`NewHost`, which copies it to `Host.token` for every `choria_provision` action.
`site`	`Site`	Every metric, as the `site` label.
`lifecycle_component`	`LifecycleComponent`	`listen`, as the startup event subject.
`logfile`, `loglevel`	`Logfile`, `Loglevel`	`cmd.run`, which copies them onto the Choria configuration.
`choria_insecure`	`Insecure`	`cmd.run`, which disables TLS and forces the `file` security provider.
`monitor_port`	`MonitorPort`	`cmd.setupPrometheus`.
`broker_provisioning_password`	`BrokerProvisionPassword`	`cmd.run`, which sets the NATS user to `provisioner`.
`cert_deny_list`	`CertDenyList`	`validateCSR`, through `matchAnyRegex`.
`jwt_verify_cert`	`JWTVerifyCert`	`validateJWT`, as a file path or a hex public key.
`jwt_signing_key`	`JWTSigningKey`	`generateServerJWT`.
`jwt_signing_token`	`JWTSigningToken`	`generateServerJWT`, re-read for every server.
`server_jwt_validity`	`ServerJWTValidity`, `ServerJWTValidityDuration`	`generateServerJWT`.
`upgrades_repository`	`UpgradesRepo`	`upgrade`, as the `release_update` repository.
`upgrades_optional`	`UpgradesOptional`	`Provision`, in the upgrade failure branch.
`leader_election`	`LeaderElection`	`hosts.Process`, to start `startElection`.
`features.jwt`	`Features.JWT`	`Provision`, to gate `fetchJWT` and `validateJWT`.
`features.pki`	`Features.PKI`	`Provision`, to gate `fetchCSR` and `validateCSR`.
`features.ed25519`	`Features.ED25519`	`Provision`, to gate `fetchEd25519PubKey` and `generateServerJWT`.
`features.upgrades`	`Features.VersionUpgrades`	`Provision`, to gate `handleHostUpgrade`.

rego_policy is declared on Config as RegoPolicy and read nowhere. OPA policies reach a node through the helper’s opa_policies reply instead.

Choria RPC actions used

Agent	Action	Purpose
`rpcutil`	`inventory`	Facts, agent list, version, and the `upgradable` flag.
`choria_provision`	`jwt`	The `provisioning.jwt` and the server’s ECDH public key.
`choria_provision`	`gen25519`	An ed25519 public key and a signature over a nonce.
`choria_provision`	`gencsr`	A CSR generated by the node.
`choria_provision`	`release_update`	An in-place binary upgrade.
`choria_provision`	`configure`	Configuration, credentials, and policies in one call.
`choria_provision`	`restart`	Restart into the new configuration.
`choria_provision`	`shutdown`	Exit with code 0, which does not trigger a systemd restart.

Glossary

fleet node: A machine running Choria Server. Provisioner's unit of work.
provisioning collective: The sub-collective that an unconfigured server joins. Provisioner forces both collectives and main_collective to this value.
provisioning.jwt: A token placed on a node that enables provisioning mode, carries the broker address, and holds the shared token.
helper: The site-supplied program that turns a server's identity and inventory into a configuration.
Organization Issuer: The ed25519 key at the root of a certificate-authority-free Choria deployment. Provisioner signs server tokens that chain to it.
server JWT: The token that Provisioner issues for a node in an Organization Issuer deployment, replacing an x509 certificate.
lifecycle event: A JSON event that Choria components publish on choria.lifecycle.event.>. Provisioner subscribes to the startup ones.
leader election: A Choria Streams primitive that names one instance in a cluster as active.
paused: The flag that a standby instance sets. Every outbound action checks it.
splay: A random delay that a server applies before acting on a restart or shutdown, spreading the load across a fleet.
site: A name for one installation, used as a label on every metric so a dashboard can aggregate across installations.

The Code Map overview returns to the start. Writing a helper gives the operator’s view of the helper contract.