Skip to main content
Enrollment runs once per host and produces the (identity.key, identity.cert) pair the agent uses for every subsequent broker call.

​
What enrollment does

certplane-agent -c <config> enroll:
  1. Acquires a file lock at <state_dir>/agent.lock.
  2. Refuses to run if identity.cert already exists.
  3. Generates an ECDSA P-256 key at identity.key (mode 0600) if missing, otherwise reuses it.
  4. Reads the bootstrap token at identity.bootstrap_token.
  5. Builds a CSR with CN = identity.name and submits it to step-ca at identity.step_ca.url, verifying the server using identity.step_ca.fingerprint or identity.step_ca.root_ca_bundle.
  6. Writes the returned identity certificate to identity.cert and removes the bootstrap token file.
The lock and the existence check make enroll safe to run from Ansible — re-runs against an already-enrolled host fail fast.

​
Generate a bootstrap token

On your step-ca host:
The CN you pass must match identity.name in the agent config. Tokens are single-use and short-lived.

​
Place the token on the host

The Ansible role does this with no_log: true and only when the identity certificate is missing.

​
Agent identity config

The minimum fields needed for enrollment:
You need either step_ca.fingerprint or step_ca.root_ca_bundle. The full schema is in Agent configuration.

​
Run enrollment

On success, the agent writes identity.crt and deletes the bootstrap token. The host is now ready to run the renewal loop.

​
Validate the config without enrolling

check validates the YAML, applies defaults, runs the same Validate() logic the agent uses at startup, and confirms expected files are reachable. It does not contact step-ca or the broker.

​
Troubleshooting

Enrollment is one-shot. To re-enroll, delete identity.cert and identity.key, generate a fresh bootstrap token, and run enroll again.
The token file at identity.bootstrap_token is missing. With Ansible, this means the certplane_agent_bootstrap_token variable was not set on this host.
The token file exists but is whitespace-only. Regenerate it with step ca token ....
The step-ca server cert is not trusted. Either set identity.step_ca.fingerprint to the SHA-256 of the step-ca root, or set identity.step_ca.root_ca_bundle to a PEM file containing it.
The broker’s server.mtls.agent_ca_bundle must trust the CA that signed identity.cert. If you rotated the step-ca intermediate after deploying the broker, redeploy the bundle.

​
Next: run the agent

Running the agent covers the run subcommand, the systemd timer, and the renewal model.