Secrets providers

The broker resolves the acme.credentials string on each policy profile through a pluggable secrets provider. The provider is selected with secrets.provider in broker.yml.

Provider	When to use
`env`	Single broker, credentials supplied via environment variables.
`file`	Credentials live on the broker’s filesystem (e.g. a sealed file rendered by Ansible).
`vault`	HashiCorp Vault KV.
`openbao`	OpenBao KV (same wire protocol as Vault).

`env` (default)

secrets:
  provider: env

The acme.credentials string in a profile is treated as an environment variable name. Set it before starting the broker:

CLOUDFLARE_DNS_API_TOKEN=... certplane-broker -c /etc/certplane/broker.yml serve

Under systemd:

/etc/systemd/system/certplane-broker.service.d/env.conf

[Service]
Environment=CLOUDFLARE_DNS_API_TOKEN=cf-token-here

`file`

secrets:
  provider: file

The acme.credentials string is interpreted as a filesystem path. The broker reads the file, trims whitespace, and uses the contents as the secret. Files must be readable by the certplane user.

install -m 0600 -o certplane -g certplane cf.token /etc/certplane/secrets/cloudflare

policy.yml

profiles:
  public_edge_main:
    type: wildcard
    dns_names: ["*.example.com"]
    acme:
      challenge: dns-01
      credentials: /etc/certplane/secrets/cloudflare

`vault` / `openbao`

secrets:
  provider: vault         # or openbao
  vault:
    address: https://vault.int.example.com:8200
    token_file: /etc/certplane/vault-token
    mount_path: secret
    kv_version: 2
    key: value
    timeout: 10s
    namespace: ""

Field	Default	Notes
`address`	—	Required when provider is `vault` or `openbao`.
`token`	—	Inline token. Avoid in production.
`token_file`	—	Path containing the Vault token. Preferred.
`mount_path`	`secret`	KV engine mount.
`kv_version`	`2`	`1` or `2`.
`key`	`value`	The key inside the secret JSON to read.
`timeout`	`10s`
`namespace`	—	Vault Enterprise only.

The acme.credentials value names the Vault path relative to mount_path. For example, with mount_path: secret and kv_version: 2:

policy.yml

profiles:
  public_edge_main:
    type: wildcard
    dns_names: ["*.example.com"]
    acme:
      challenge: dns-01
      credentials: certplane/cloudflare/example-com

…reads secret/data/certplane/cloudflare/example-com and returns the value at data.value (or whatever vault.key is set to). End-to-end walkthrough: Vault and OpenBao secrets.

Choosing a provider

Just bringing up the broker? Use env. Two seconds to set up.
Production single-broker? file is fine if you already render secrets via your config management tool.
Multi-broker or centralized secret rotation? vault or openbao. Tokens can be short-lived and rotated independently of the broker process.

Get Started

Setup

Policy

Configuration

Guides

`env` (default)

`file`

`vault` / `openbao`

Choosing a provider

​env (default)

​file

​vault / openbao

​Choosing a provider

`env` (default)

`file`

`vault` / `openbao`

Choosing a provider