> ## Documentation Index
> Fetch the complete documentation index at: https://certplane.kippel.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy with the Ansible roles

> End-to-end deployment of certplane-broker and certplane-agent using the official certplane_broker and certplane_agent roles.

Certplane ships two Ansible roles in the [`ansible/`](https://github.com/TaconeoMental/Certplane/tree/main/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:

```yaml site.yml theme={null}
- 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

```yaml group_vars/certplane_broker.yml theme={null}
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)

```yaml theme={null}
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

1. Creates the `certplane` system user/group.
2. Copies the broker binary to `certplane_broker_binary_dest`.
3. Creates `/etc/certplane`, `/etc/certplane/tls`, `/etc/certplane/ca`, `/var/lib/certplane`, and `/var/lib/certplane/acme`.
4. Deploys TLS cert/key, agent CA bundle, ACME account key (if provided), and the policy file.
5. Renders `broker.yml` from [`templates/broker.yml.j2`](https://github.com/TaconeoMental/Certplane/blob/main/ansible/roles/certplane_broker/templates/broker.yml.j2).
6. 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

```yaml host_vars/edge01.yml theme={null}
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)

```yaml theme={null}
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

1. Creates the `certplane` system user/group.
2. Installs the agent binary at `certplane_agent_binary_dest`.
3. Deploys the issuer CA bundle, broker CA bundle, and (optionally) the `step-ca` root bundle.
4. Renders `agent.yml` from [`templates/agent.yml.j2`](https://github.com/TaconeoMental/Certplane/blob/main/ansible/roles/certplane_agent/templates/agent.yml.j2).
5. **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.
6. Installs `certplane-agent.service` (oneshot, `check` then `run`) and `certplane-agent.timer` (boots after 1min, fires every 6h with 5min jitter).
7. 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](/guides/vault-secrets).