vault-operations

name	vault-operations
description	Operational runbook for the vault-agent — safe secret handling, mount-deletion safety, PKI best practices, and how Vault feeds this cluster via External Secrets.

HashiCorp Vault Operations Runbook

Use these procedures when managing Vault via the MCP tools. Vault is the source of truth for this cluster's secrets; treat every write and delete as potentially production-impacting.

Secret confidentiality (default behavior)

• When reading with read_secret, show key names but mask values (e.g. api_key: ****) unless the user explicitly asks to reveal them.
• Never echo a full secret value into a summary, table, or log line by default.
• Use list_secrets to enumerate paths without exposing values.

KV path conventions

• KV v2 stores data under secret/data/<path> internally, but users reference it as secret/<path>. Accept both and normalize.
• This cluster's known paths include secret/kagent/*, secret/telegram, secret/f5, secret/whatsapp (consumed by External Secrets Operator).

Deleting a mount (high risk — irreversible)

delete_mount destroys ALL secrets in the mount. Before doing it:

1. list_secrets under the mount to enumerate exactly what will be lost.
2. Warn that this is irreversible and breaks any ExternalSecret syncing from those paths.
3. Require explicit confirmation that names the mount.

Deleting a secret

1. Check whether an ExternalSecret references the path before deleting — deleting it will make the synced Kubernetes Secret go stale / fail to refresh.
2. delete_secret only after confirming impact.

Creating mounts / writing secrets

• create_mount (KV v1, KV v2, or PKI) — confirm the type; KV v2 is the default choice for app secrets (versioning + soft delete).
• write_secret is gated behind approval — describe the path and key names (not values) before writing.

PKI best practices

• enable_pki then create_pki_issuer. Prefer issuing leaf certs from an intermediate CA, not the root.
• Roles (create_pki_role) constrain allowed domains and TTLs — set short TTLs for leaf certificates and rotate.
• issue_pki_certificate produces a cert+key; treat the private key as a secret (mask it).
• Warn on long TTLs and on issuing directly from a root CA.

Integration note (this cluster)

Vault is fronted by External Secrets Operator via the vault-backend ClusterSecretStore. App secrets flow Vault → ExternalSecret → Kubernetes Secret. So a change in Vault is not live in a pod until ESO re-syncs (and the pod re-reads it). Mention this when a user expects an instant effect from a Vault write.

Error code cheat sheet

• 403 = permission denied (token policy lacks the capability on that path)
• 404 = path/mount not found
• 400 = invalid request (bad parameters)