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.
The broker needs access to sensitive values such as DNS provider API tokens used to complete ACME dns-01 challenges. Rather than embedding these values directly in broker.yml, Certplane supports four pluggable secrets providers that you configure under the secrets section of the broker config. Each provider resolves a secret by name at runtime, keeping credentials out of your configuration files and version control.
The env provider is the default and the simplest way to get started. It
requires no additional configuration beyond setting environment variables
before you start the broker.
Do not store plain-text secrets in broker.yml itself. Use one of the
secrets providers below so that sensitive values are kept outside your
configuration files and are not accidentally committed to version control
or included in configuration diffs.
Secret references
Wherever Certplane expects a sensitive value (such as a DNS provider
credential), you supply a secret reference — a name that the active
provider resolves at runtime. The meaning of the name depends on which
provider is configured:
| Provider | Name means |
|---|
env | Environment variable name |
file | Absolute file path |
vault | Vault secret path |
openbao | OpenBao secret path |
Configuring a provider
Set secrets.provider in broker.yml to choose a provider. Only one
provider is active at a time.
The env provider (default) resolves secret names as environment
variable names. The broker reads the named variable from its process
environment at the point the secret is needed.For example, if a DNS credential reference uses the name
CLOUDFLARE_DNS_API_TOKEN, the broker reads the value of the
$CLOUDFLARE_DNS_API_TOKEN environment variable. Set that variable
before starting the broker:export CLOUDFLARE_DNS_API_TOKEN=your-token-here
certplane-broker --config /etc/certplane/broker.yml
secrets are required for this provider. The file provider resolves secret names as file paths on the local
filesystem. Each secret is stored in its own file, with the secret
value as the file’s contents.For example, a credential reference named
/etc/certplane/secrets/cloudflare-token causes the broker to read
the contents of that file at runtime. Store one secret per file and
restrict file permissions appropriately:echo -n "your-token-here" > /etc/certplane/secrets/cloudflare-token
chmod 600 /etc/certplane/secrets/cloudflare-token
secrets are required for this provider. The vault provider reads secrets from a HashiCorp Vault
KV secrets engine. Secret names are treated as Vault secret paths.secrets:
provider: vault
vault:
address: https://vault.internal.example.com:8200
token: s.exampletoken # or use token_file
token_file: /etc/certplane/vault-token
mount_path: secret # default: secret
kv_version: 2 # 1 or 2, default: 2
key: value # field name within the secret, default: value
namespace: "" # Vault Enterprise namespace (optional)
timeout: 10s # default: 10s
URL of the Vault server, for example
https://vault.internal.example.com:8200.
Vault token for authentication. Either token or token_file must
be provided.
Path to a file containing the Vault token. Either token_file or
token must be provided. The file is read once at startup.
Mount path of the KV secrets engine in Vault.
KV engine version. Accepted values: 1 or 2. Use 2 for the KV
v2 engine (versioned secrets), which is the default for new Vault
deployments.
The field name within each Vault secret to read. For KV v2 secrets
that store a single value, the conventional field name is value.
Vault Enterprise namespace. Leave empty for open-source Vault.
Timeout for Vault API calls. Accepts Go duration strings such as
10s or 30s.
The openbao provider reads secrets from OpenBao,
a community fork of Vault. Its configuration is identical to the vault
provider — only the provider value changes.secrets:
provider: openbao
vault:
address: https://openbao.internal.example.com:8200
token_file: /etc/certplane/openbao-token
mount_path: secret
kv_version: 2
timeout: 10s
vault tab apply equally to the openbao
provider. The shared vault config block is used for both providers. 