Skip to main content

HashiCorp Vault / OpenBao

Read a distribution credential's value from a Vault KV secret at the moment it is used. OpenBao is API-compatible — configure it exactly as a Vault store; everything on this page applies to both. For the concept, the never-cached reading model and everything the store types share, see External secret stores.

1. Prepare Vault​

Store the value you want CertAutoPilot to use. Each credential maps to one field inside one secret:

vault kv put secret/apps/f5/prod password='<the F5 admin password>'

Create a policy that grants read only on the paths CertAutoPilot needs. Deployments use nothing beyond read — CertAutoPilot never writes to or lists your secrets:

# certautopilot-read.hcl  (KV v2 — note the /data/ segment)
path "secret/data/apps/*" {
  capabilities = ["read"]
}

On a KV v1 mount the path has no data/ segment:

path "secret/apps/*" {
  capabilities = ["read"]
}

The Test button additionally probes the mount itself (sys/mounts/<mount>/tune), which the policy above does not grant. That is deliberate — deployments never need it. Test then still reports the store as reachable, with the note "mount tune permission denied — reads may still work". If you would rather see a clean result, add:

path "sys/mounts/secret/tune" {
  capabilities = ["read"]
}

Then create the login CertAutoPilot will use. An AppRole is preferable to a raw token because its secret_id can be rotated on Vault's side:

vault policy write certautopilot-read certautopilot-read.hcl
vault write auth/approle/role/certautopilot token_policies=certautopilot-read
vault read  auth/approle/role/certautopilot/role-id      # → role_id
vault write -f auth/approle/role/certautopilot/secret-id # → secret_id

The role_id and secret_id those last two commands print are the pair you will enter in step 2. If you prefer a plain token instead, create a periodic orphan token — a default token expires with its TTL and takes every deployment down with it:

vault token create -policy=certautopilot-read -orphan -period=768h

A periodic token still has to be renewed within its period on Vault's side — one more reason the AppRole is the recommended option.

2. Add the login credential in CertAutoPilot​

Under Settings → Distribution → Credentials, add a normal stored credential:

  • Vault AppRole — role_id and secret_id, or
  • Vault Token — a token.

This one is deliberately a stored credential. A store cannot authenticate with a credential that itself has to be read from a store; the chain stops at one hop, so a loop is impossible rather than merely detected.

3. Add the secret store​

Under Settings → Distribution → Secret Stores → Add Secret Store:

FieldNotes
Store Typevault. Fixed after creation — it selects the implementation that interprets both this store's settings and every credential reference pointing at it.
Addresshttps://vault.internal:8200. HTTPS is required, except http://localhost or http://127.0.0.1 for local development. Credentials embedded in the URL are rejected.
KV Mount PathRequired. The mount as shown by vault secrets list — usually secret.
KV Versionkv2 (versioned, the default for new mounts) or kv1. The two use different API paths, so this must match the mount.
NamespaceVault Enterprise / HCP namespace. Leave empty for open-source Vault and OpenBao.
Auth CredentialThe Vault Token or AppRole credential from step 2.
CA CertificatePEM trust anchor, if Vault's certificate is not publicly trusted. Preferred over disabling verification.
TimeoutPer-request timeout, in seconds.

Saving does not contact Vault. Use Test on the list afterwards; it authenticates and reports what it found, without reading any of your secrets.

4. Point a credential at it​

Add a credential as usual, then set Secret Source to External secret store:

FieldValue
Secret Storecorp-vault
Secret PathThe path inside the mount — no mount prefix, no data/. A secret written as secret/apps/f5/prod on a secret mount is entered as apps/f5/prod.
FieldThe key inside that secret, e.g. password.

Choose the Credential Type exactly as you would for a stored credential; every module behaves identically. Where a value comes from is independent of what it is. What to put in the field for each credential type is the field-mapping table.

Revisions​

On a KV v2 mount, the secret's revision is recorded in each deployment's job log — the only drift signal available without exposing anything about the value; comparing two runs shows whether the underlying secret changed between them. KV v1 has no revision concept, so those reads are logged as (no revision).

See also​