Skip to main content

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.

If you use HashiCorp Vault or OpenBao to manage secrets, Certplane’s broker can read sensitive values (like DNS API tokens) directly from Vault rather than from environment variables or files. This keeps credentials out of your shell environment and lets you manage rotation centrally through Vault’s API.

​
Prerequisites

Before you begin, confirm the following:
  • Vault is running and its API is reachable from the broker host.
  • You have a Vault token with read capability on the secret path you plan to use.
  • The KV secrets engine is mounted and enabled in your Vault instance.
1

Write the secret to Vault

Store your Cloudflare DNS API token (or any other credential) as a KV secret. The example below uses the KV v2 engine mounted at secret:
vault kv put secret/certplane/cloudflare value="your-cloudflare-token"
Certplane reads the field named by secrets.vault.key from this secret. The default key name is value, matching the command above.
Create a dedicated Vault policy that restricts the broker token to only the paths it needs. A minimal policy for the path above looks like this:
path "secret/data/certplane/*" {
  capabilities = ["read"]
}
Apply it with vault policy write certplane-broker certplane-broker.hcl, then generate a token with vault token create -policy=certplane-broker.
2

Write the Vault token to a file

Certplane reads the Vault token from a file rather than an environment variable, so the token is never exposed through the process environment:
echo "hvs.YOUR_VAULT_TOKEN" > /etc/certplane/vault-token
chmod 600 /etc/certplane/vault-token
Ensure the file is readable only by the user that runs the broker process.
3

Configure the broker to use the Vault provider

Update broker.yml to set secrets.provider to vault and fill in the connection details:
secrets:
  provider: vault
  vault:
    address: https://vault.example.com:8200
    token_file: /etc/certplane/vault-token
    mount_path: secret
    kv_version: 2
    key: value
    timeout: 10s
kv_version controls which KV Secrets Engine API Certplane uses to fetch the secret:
  • 2 (default) — KV Secrets Engine v2. Secrets have full version history and are stored under the secret/data/<path> prefix internally. Use this for new Vault deployments.
  • 1 — KV Secrets Engine v1. No versioning; secrets are stored directly at secret/<path>. Use this only if your Vault instance has not upgraded to KV v2.
Both versions are supported; set kv_version to match what your Vault mount actually uses.
4

Reference the secret in your profile config

In policy.yml, set acme.credentials to the Vault path of the secret (relative to the mount). Certplane appends this to mount_path when constructing the Vault API call:
profiles:
  public_wildcard:
    cert_type: wildcard
    dns_names:
      - "*.example.com"
    acme_challenge: dns-01
    renew_before: 720h
The acme_challenge field in policy.yml sets the challenge type for the profile. The Cloudflare credential is configured in the broker’s issuer.acme section — the broker uses it automatically when completing dns-01 challenges for this profile.
The value certplane/cloudflare in the Vault path matches the secret you wrote in step 1 (secret/certplane/cloudflare minus the mount prefix secret).

​
Using OpenBao

OpenBao is an open-source fork of Vault with a compatible API. Certplane supports it natively — use the same configuration as above but set provider to openbao: 
secrets:
  provider: openbao
  vault:
    address: https://openbao.example.com:8200
    token_file: /etc/certplane/vault-token
    mount_path: secret
    kv_version: 2
    key: value
    timeout: 10s
All other fields (mount_path, kv_version, key, timeout) behave identically. The vault sub-key is reused for OpenBao configuration — there is no separate openbao block.