> ## 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.

# Almacena los secretos de Certplane en HashiCorp Vault

> Configura el broker de Certplane para leer credenciales sensibles como tokens de API DNS directamente desde un motor de secretos KV de HashiCorp Vault u OpenBao.

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.

<Steps>
  <Step title="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`:

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

    <Tip>
      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í:

      ```hcl theme={null}
      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`.
    </Tip>
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Configura el broker para usar el proveedor Vault">
    Actualiza `broker.yml` para definir `secrets.provider` como `vault` y rellena los detalles de conexión:

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

    <Note>
      `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.
    </Note>
  </Step>

  <Step title="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:

    ```yaml theme={null}
    profiles:
      public_wildcard:
        type: wildcard
        dns_names:
          - "*.example.com"
        acme:
          challenge: dns-01
          credentials: certplane/cloudflare
        renew_before: 720h
    ```

    <Note>
      `acme.credentials` es una referencia a un secreto, resuelta por el proveedor de secretos configurado en el broker. Con el proveedor de Vault, el valor es la ruta del secreto relativa a `secrets.vault.mount_path`. El broker lee el campo nombrado por `secrets.vault.key` (por defecto `value`) de ese secreto para obtener el token real del proveedor de DNS.
    </Note>

    El valor `certplane/cloudflare` del ejemplo anterior coincide con el secreto que escribiste en el paso 1 (`secret/certplane/cloudflare` menos el prefijo de montaje `secret`).
  </Step>
</Steps>

## Usar OpenBao

[OpenBao](https://openbao.org/) 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`:

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