Deploy with the Ansible roles

Certplane ships two Ansible roles in the ansible/ directory of the source repo:

certplane_broker — installs the broker binary, lays out config and TLS material, deploys the policy file, and manages the systemd service.
certplane_agent — installs the agent binary, deploys CA bundles and config, performs first-time enrollment with a bootstrap token, and manages the systemd timer.

Both roles target Debian Bookworm and Ubuntu Jammy/Noble out of the box.

Layout

Add the roles to your control repo (roles/ symlinked or vendored). A minimal play:

site.yml

- name: Certplane broker
  hosts: certplane_broker
  become: true
  roles:
    - certplane_broker

- name: Certplane agents
  hosts: certplane_agents
  become: true
  roles:
    - certplane_agent

`certplane_broker` role

Required variables

group_vars/certplane_broker.yml

certplane_broker_binary: /path/on/control/host/to/certplane-broker
certplane_broker_tls_cert_src: files/broker/broker.crt
certplane_broker_tls_key_src: files/broker/broker.key
certplane_broker_agent_ca_bundle_src: files/ca/agent-identity-ca-bundle.crt
certplane_broker_policy_src: files/broker/policy.yml

certplane_broker_acme_directory_url: https://acme-v02.api.letsencrypt.org/directory
certplane_broker_acme_account_email: admin@example.com
certplane_broker_acme_dns_provider: cloudflare
# certplane_broker_acme_account_key_src: files/broker/account.key   # optional

Useful variables (with defaults)

certplane_broker_user: certplane
certplane_broker_group: certplane
certplane_broker_binary_dest: /usr/local/bin/certplane-broker
certplane_broker_config_dir: /etc/certplane
certplane_broker_state_dir: /var/lib/certplane

certplane_broker_listen: ":8443"
certplane_broker_tls_min_version: "1.2"
certplane_broker_read_header_timeout: 5s
certplane_broker_read_timeout: 10s
certplane_broker_write_timeout: 60s
certplane_broker_idle_timeout: 120s

certplane_broker_policy_path: /etc/certplane/policy.yml
certplane_broker_policy_watch: false

certplane_broker_secrets_provider: env       # env | file | vault | openbao
certplane_broker_vault_mount_path: secret
certplane_broker_vault_kv_version: 2
certplane_broker_vault_key: value
certplane_broker_vault_timeout: 10s

certplane_broker_store_driver: sqlite
certplane_broker_store_path: /var/lib/certplane/broker.db

certplane_broker_audit_enabled: true
certplane_broker_audit_failure_mode: fail_open
certplane_broker_audit_mirror_to_log: false

certplane_broker_rate_limit_per_identity_per_hour: 50
certplane_broker_rate_limit_per_identity_profile_per_hour: 20

certplane_broker_log_level: info
certplane_broker_log_format: json
certplane_broker_log_destination: stdout

When certplane_broker_secrets_provider is vault or openbao, also set certplane_broker_vault_address and one of certplane_broker_vault_token / certplane_broker_vault_token_file.

What the role does

Creates the certplane system user/group.
Copies the broker binary to certplane_broker_binary_dest.
Creates /etc/certplane, /etc/certplane/tls, /etc/certplane/ca, /var/lib/certplane, and /var/lib/certplane/acme.
Deploys TLS cert/key, agent CA bundle, ACME account key (if provided), and the policy file.
Renders broker.yml from templates/broker.yml.j2.
Installs and enables certplane-broker.service. Any change to TLS material, the policy file, or the rendered config triggers a service restart.

`certplane_agent` role

Required variables

host_vars/edge01.yml

certplane_agent_binary: /path/on/control/host/to/certplane-agent
certplane_agent_identity_name: edge01.h.int.example.com
certplane_agent_issuer_ca_bundle_src: files/ca/agent-identity-ca-bundle.crt
certplane_agent_broker_ca_bundle_src: files/ca/broker-server-ca-bundle.crt
certplane_agent_broker_url: https://certplane-broker.int.example.com:8443

certplane_agent_step_ca_url: https://ca.int.example.com
# Either fingerprint or root_ca_bundle_src
certplane_agent_step_ca_fingerprint: "sha256:aabbcc..."
# certplane_agent_step_ca_root_ca_bundle_src: files/ca/step-ca-root.crt

# Provided per-host, only used until the host is enrolled
certplane_agent_bootstrap_token: "{{ lookup('pipe', 'step ca token ' + certplane_agent_identity_name) }}"

certplane_agent_certificates:
  - name: edge-wildcard
    profile: public_edge_main
    dns_names:
      - "*.example.com"
    key: /var/lib/certplane/agent/service.key
    cert: /var/lib/certplane/agent/service.crt
    chain: /var/lib/certplane/agent/service.chain.crt
    fullchain: /var/lib/certplane/agent/service.fullchain.crt
    reload_command: "systemctl reload traefik"
    reload_timeout: 30s
    renew_before: 720h

Useful variables (with defaults)

certplane_agent_user: certplane
certplane_agent_group: certplane
certplane_agent_binary_dest: /usr/local/bin/certplane-agent
certplane_agent_config_dir: /etc/certplane
certplane_agent_state_dir: /var/lib/certplane/agent

certplane_agent_identity_cert: /var/lib/certplane/agent/identity.crt
certplane_agent_identity_key: /var/lib/certplane/agent/identity.key
certplane_agent_identity_renew_before: 8h
certplane_agent_identity_warn_before: 24h

certplane_agent_step_ca_timeout: 10s
certplane_agent_broker_timeout: 30s

certplane_agent_bootstrap_token_path: /etc/certplane/bootstrap-token

certplane_agent_timer_on_boot_sec: 1min
certplane_agent_timer_on_active_sec: 6h
certplane_agent_timer_randomized_delay: 5min

certplane_agent_log_level: info
certplane_agent_log_format: text
certplane_agent_log_destination: stderr

What the role does

Creates the certplane system user/group.
Installs the agent binary at certplane_agent_binary_dest.
Deploys the issuer CA bundle, broker CA bundle, and (optionally) the step-ca root bundle.
Renders agent.yml from templates/agent.yml.j2.
Enrolls the host once. If identity.crt does not exist and certplane_agent_bootstrap_token is defined, the role writes the token (no_log: true) and runs certplane-agent ... enroll as the certplane user. On success the token file is removed by the binary.
Installs certplane-agent.service (oneshot, check then run) and certplane-agent.timer (boots after 1min, fires every 6h with 5min jitter).
Enables and starts the timer.

The enrollment step is idempotent: once identity.crt exists, future runs of the role skip both the token deployment and the enroll command.

Recommended secrets handling

Pass certplane_agent_bootstrap_token from your inventory via Ansible Vault or a runtime lookup (step ca token).
Never check raw step-ca tokens into git — they are short-lived but still single-use.
For DNS provider tokens consumed by the broker, prefer secrets.provider: vault. See Vault and OpenBao secrets.

Get Started

Setup

Policy

Configuration

Guides

Deploy with the Ansible roles

Layout

`certplane_broker` role

Required variables

Useful variables (with defaults)

What the role does

`certplane_agent` role

Required variables

Useful variables (with defaults)

What the role does

Recommended secrets handling

​Layout

​certplane_broker role

​Required variables

​Useful variables (with defaults)

​What the role does

​certplane_agent role

​Required variables

​Useful variables (with defaults)

​What the role does

​Recommended secrets handling

Layout

`certplane_broker` role

Required variables

Useful variables (with defaults)

What the role does

`certplane_agent` role

Required variables

Useful variables (with defaults)

What the role does

Recommended secrets handling