Skip to main content
The hosts map binds each managed host’s machine identity to the set of certificate profiles it can request. 
hosts:
  edge01:
    identity: edge01.h.int.example.com
    profiles:
      - public_edge_main

  api01:
    identity: api01.h.int.example.com
    profiles:
      - api_san
      - public_edge_main

​
Fields

FieldTypeRequiredNotes
identitystringyesThe CN of the host’s identity certificate (issued by step-ca).
profilesstring[]yesNon-empty list of profile names the host may request.
The top-level map key (edge01, api01) is a human-readable label only — it appears in audit events and policy validation output. The broker authorizes by identity, not by label.

​
Matching rules

  • identity must be a stable CN — the agent presents it as the client certificate’s CN over mTLS.
  • Two host entries must not share the same identity. The policy compiler rejects duplicates.
  • profiles must reference profiles that exist in the same policy file.
  • An agent that asks for a profile not in its host’s profiles list is rejected with an authorization failure, regardless of whether the profile itself exists.

​
Adding a new host

  1. Issue a step-ca bootstrap token for the new CN.
  2. Add a host entry to the policy file: 
    hosts:
  edge02:
    identity: edge02.h.int.example.com
    profiles:
      - public_edge_main
  3. If policy.watch: true is set on the broker, the change goes live immediately. Otherwise restart the broker.
  4. Deploy the agent and run enroll on the host.

​
Removing a host

Delete its hosts.<label> entry. With policy.watch: true the change applies on next file change. The host’s identity certificate may continue to be valid (step-ca decides that), but the broker will reject all of its issuance requests.

​
Validate the host list

certplane-broker -c /etc/certplane/broker.yml policy validate --policy /etc/certplane/policy.yml
The output includes the number of compiled identities: 
policy ok: hash=abc123… profiles=2 identities=42