HashiCorp Vault Operations Master Class #

Production-focused reference for operating HashiCorp Vault safely: health checks, authentication, secrets engines, policies, tokens, leases, audit devices, snapshots, and recovery workflows.

Overview #

HashiCorp Vault centralizes secrets and provides encryption, identity-based access, dynamic credentials, and auditable secret delivery. Treat policy changes, token creation, secret writes, lease revocation, sealing, and recovery operations as governed production changes. Start with read-only health and configuration checks, use short-lived credentials, and never place real secret values in shell history or documentation.

Client Context and Health #

Show the CLI version:

vault version

Set the Vault address and use a token supplied by an approved secret manager:

export VAULT_ADDR="https://vault.example.com:8200"

Check server health without authenticating:

vault status

Request the health endpoint as JSON:

curl --silent --show-error "$VAULT_ADDR/v1/sys/health"

Show the authenticated identity and token metadata:

vault token lookup

Do not export long-lived root tokens. Prefer workload identity, OIDC, AppRole with response wrapping, or another narrowly scoped authentication method.

Authentication Methods #

List enabled authentication methods:

vault auth list

Inspect an authentication mount:

vault read sys/auth/approle/tune

Enable AppRole only through an approved change:

vault auth enable approle

Authenticate with OIDC interactively:

vault login -method=oidc

Authenticate an automated workload with environment-provided identifiers:

vault write auth/approle/login role_id="$VAULT_ROLE_ID" secret_id="$VAULT_SECRET_ID"

Never paste a Secret ID, token, password, or unseal key directly into a command that will be retained in shell history.

Secrets Engines #

List mounted secrets engines:

vault secrets list

Inspect a mount configuration:

vault read sys/mounts/secret/tune

Enable a KV v2 engine after approval:

vault secrets enable -path=platform kv-v2

Write a secret from approved environment variables rather than literal values:

vault kv put platform/app username="$APP_USERNAME" password="$APP_PASSWORD"

Read secret data:

vault kv get platform/app

Read only field metadata where possible:

vault kv metadata get platform/app

List keys without retrieving secret values:

vault kv list platform/

Soft-delete the latest secret version only after impact review:

vault kv delete platform/app

Policies and Access Review #

List policies:

vault policy list

Read a policy:

vault policy read platform-readonly

Validate a policy file locally before applying it:

vault policy fmt -check platform-readonly.hcl

Write an approved policy:

vault policy write platform-readonly platform-readonly.hcl

Review effective capabilities for a path:

vault token capabilities platform/data/app

A least-privilege policy should grant only required paths and capabilities. Avoid wildcard access to sys/*, auth/*, or all secret mounts.

Tokens and Leases #

Inspect the current token:

vault token lookup

List accessors without exposing token values:

vault list auth/token/accessors

Create a short-lived token only for an approved operational need:

vault token create -policy=platform-readonly -ttl=30m -explicit-max-ttl=1h

Inspect a lease:

vault lease lookup database/creds/reporting

Renew a renewable lease:

vault lease renew database/creds/reporting/LEASE_ID

Revoke a compromised or no-longer-required lease after impact review:

vault lease revoke database/creds/reporting/LEASE_ID

Audit Devices #

List configured audit devices:

vault audit list

Enable a file audit device only after validating destination permissions, rotation, capacity, and log shipping:

vault audit enable file file_path=/var/log/vault/audit.log

Vault hashes most sensitive values in audit records, but audit logs still contain operational metadata. Restrict access and monitor for write failures because Vault may reject requests when it cannot write to an enabled audit device.

Raft Storage and Snapshots #

List integrated-storage peers:

vault operator raft list-peers

Save an encrypted, access-controlled Raft snapshot:

vault operator raft snapshot save vault-raft.snap

Inspect snapshot metadata without restoring it:

vault operator raft snapshot inspect vault-raft.snap

Restoring a snapshot overwrites cluster state. Perform it only under an approved recovery plan with a verified backup, maintenance window, and rollback path:

vault operator raft snapshot restore vault-raft.snap

Seal and Recovery Boundaries #

Check seal state:

vault status

Sealing immediately prevents most Vault operations and can cause an application outage. Never run this command without explicit production approval:

vault operator seal

Unseal or recovery shares must remain separated among authorized custodians. Never record them in tickets, chat, repositories, CI variables, or shared command history.

Safe Production Workflow #

1. Confirm the target VAULT_ADDR, namespace, cluster role, and maintenance scope.
2. Run vault status, vault token lookup, and the relevant list/read command.
3. Capture current policies, mounts, audit devices, and peer state without recording secret values.
4. Prepare the smallest possible change and peer-review its policy and impact.
5. Obtain approval for writes, revocations, sealing, restore, or access expansion.
6. Apply the approved command using short-lived credentials.
7. Re-run read-only checks and inspect audit evidence.
8. Revoke temporary credentials and store evidence without secrets.

Incident Triage #

Confirm availability and seal state:

vault status
curl --silent --show-error "$VAULT_ADDR/v1/sys/health"

Review integrated-storage membership:

vault operator raft list-peers

Check audit device configuration:

vault audit list

Inspect current token lifetime and policies:

vault token lookup

Do not respond to an outage by disabling audit, issuing a root token, forcing a snapshot restore, or sealing the cluster without an approved incident command decision and a verified recovery path.