Saltar al contenido principal

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.

Si usas HashiCorp Vault u OpenBao para gestionar secretos, el broker de Certplane puede leer valores sensibles (como tokens de API DNS) directamente desde Vault en lugar de desde variables de entorno o archivos. Esto mantiene las credenciales fuera del entorno de tu shell y te permite gestionar la rotación de forma centralizada mediante la API de Vault.

​
Requisitos previos

Antes de empezar, confirma lo siguiente:
  • Vault está en ejecución y su API es accesible desde el host del broker.
  • Tienes un token de Vault con la capacidad read sobre la ruta de secreto que planeas usar.
  • El motor de secretos KV está montado y habilitado en tu instancia de Vault.
1

Escribe el secreto en Vault

Almacena tu token de API DNS de Cloudflare (o cualquier otra credencial) como un secreto KV. El ejemplo siguiente usa el motor KV v2 montado en secret:
vault kv put secret/certplane/cloudflare value="your-cloudflare-token"
Certplane lee el campo nombrado por secrets.vault.key de este secreto. El nombre de campo predeterminado es value, coincidiendo con el comando anterior.
Crea una política de Vault dedicada que restrinja el token del broker solo a las rutas que necesita. Una política mínima para la ruta anterior se ve así:
path "secret/data/certplane/*" {
  capabilities = ["read"]
}
Aplícala con vault policy write certplane-broker certplane-broker.hcl, luego genera un token con vault token create -policy=certplane-broker.
2

Escribe el token de Vault en un archivo

Certplane lee el token de Vault desde un archivo en lugar de una variable de entorno, para que el token nunca se exponga a través del entorno de proceso:
echo "hvs.YOUR_VAULT_TOKEN" > /etc/certplane/vault-token
chmod 600 /etc/certplane/vault-token
Asegúrate de que el archivo sea legible solo para el usuario que ejecuta el proceso del broker.
3

Configura el broker para usar el proveedor Vault

Actualiza broker.yml para definir secrets.provider como vault y rellena los detalles de conexión:
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 controla qué API del motor de secretos KV usa Certplane para obtener el secreto:
  • 2 (predeterminado) — Motor de secretos KV v2. Los secretos tienen historial completo de versiones y se almacenan internamente bajo el prefijo secret/data/<path>. Úsala para nuevos despliegues de Vault.
  • 1 — Motor de secretos KV v1. Sin versionado; los secretos se almacenan directamente en secret/<path>. Úsala solo si tu instancia de Vault no se ha actualizado a KV v2.
Ambas versiones están soportadas; define kv_version para que coincida con lo que tu montaje de Vault realmente usa.
4

Referencia el secreto en la configuración de tu perfil

En policy.yml, define acme.credentials con la ruta del secreto en Vault (relativa al montaje). Certplane lo añade a mount_path al construir la llamada a la API de Vault:
profiles:
  public_wildcard:
    cert_type: wildcard
    dns_names:
      - "*.example.com"
    acme_challenge: dns-01
    renew_before: 720h
El campo acme_challenge en policy.yml define el tipo de desafío para el perfil. La credencial de Cloudflare se configura en la sección issuer.acme del broker: el broker la usa automáticamente al completar los desafíos dns-01 para este perfil.
El valor certplane/cloudflare en la ruta de Vault coincide con el secreto que escribiste en el paso 1 (secret/certplane/cloudflare menos el prefijo de montaje secret).

​
Usar OpenBao

OpenBao es un fork de código abierto de Vault con una API compatible. Certplane lo soporta de forma nativa: usa la misma configuración que la anterior pero define provider como 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
Todos los demás campos (mount_path, kv_version, key, timeout) se comportan de forma idéntica. La subclave vault se reutiliza para la configuración de OpenBao: no hay un bloque openbao separado.