Usage

Use VAULT through bao and HTTP APIs for KV secrets, Transit encryption, and AppRole credentials.

After configuring and deploying VAULT, use this page to get started. The following engines and authentication methods are enabled by default:

Path	Type	Purpose
`secret/`	KV v2 secrets engine	Versioned static secrets such as passwords, API keys, and certificates
`transit/`	Transit secrets engine	Encryption as a service; applications send data for encryption/decryption while keys remain in VAULT
`auth/approle/`	AppRole authentication	Machine credentials for applications and automation
`auth/token/`	Token authentication	Built-in; maximum lease adjusted to ten years

OpenBao’s API is largely compatible with HashiCorp Vault, so common Vault client libraries and tools generally work directly. See the OpenBao documentation for full usage.

Endpoint

All clients should use the service domain over HTTPS and validate the server certificate with Pigsty CA:

Item	Value
Address	`https://vault.pigsty:8200`
CA certificate	`/etc/pki/ca.crt` on managed nodes; `files/pki/ca/ca.crt` on the admin node
TLS version	TLS 1.3 minimum

In a three-member cluster, vault.pigsty points to the VIP and HAProxy forwards to the active member. Direct standby access also works; the standby forwards requests to the active member.

export BAO_ADDR=https://vault.pigsty:8200
export BAO_CACERT=/etc/pki/ca.crt

bao is installed with openbao on VAULT members. Other nodes can use curl with the HTTP API, or install openbao to obtain bao.

Run these examples as root on a VAULT member with the root token. See Administrator Credentials:

sudo -i                                     # BAO_ADDR and BAO_CACERT are set by /etc/profile.d/bao.sh
read -rs BAO_TOKEN && export BAO_TOKEN      # Enter the root token; input is hidden
bao secrets list                            # List enabled secrets engines
bao auth list                               # List enabled authentication methods

Use the root token only for administration. Issue credentials with minimal privileges to applications.

KV Secrets

secret/ uses KV v2, which saves a new version on every write:

bao kv put secret/app/db username=dbuser_app password='S3cret!'   # Write a secret
bao kv get secret/app/db                                          # Read the latest version
bao kv get -field=password secret/app/db                          # Read one field
bao kv get -version=1 secret/app/db                               # Read a historical version
bao kv list secret/app                                            # List secrets under a path
bao kv metadata get secret/app/db                                 # Inspect version metadata
bao kv delete secret/app/db                                       # Soft-delete the latest version; recover with undelete

KV v2 policies and HTTP APIs use secret/data/<path> for secret reads/writes and secret/metadata/<path> for metadata.

Transit Encryption

transit/ provides encryption as a service. Applications send data for encryption or decryption without handling keys, suitable for encrypting sensitive database fields in the application layer.

bao write -f transit/keys/app                                    # Create the app encryption key
bao write transit/encrypt/app plaintext=$(echo -n 'hello' | base64)
# ciphertext    vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==
bao write -field=plaintext transit/decrypt/app \
  ciphertext='vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==' | base64 -d
bao write -f transit/keys/app/rotate                             # Rotate the key; old ciphertext remains readable

Base64-encode plaintext first. After rotation, new data uses the new key version, while older ciphertext remains decryptable. Use transit/rewrap/app to rewrap old ciphertext with the new version.

Issue Application Credentials

Create a policy with only the permissions each application needs, then issue machine credentials through AppRole:

# 1. Create a policy: read/write secret/app/ and use the app Transit key only
bao policy write app - <<'EOF'
path "secret/data/app/*"     { capabilities = ["create", "read", "update", "delete", "list"] }
path "secret/metadata/app/*" { capabilities = ["read", "list"] }
path "transit/encrypt/app"   { capabilities = ["update"] }
path "transit/decrypt/app"   { capabilities = ["update"] }
EOF

# 2. Create an AppRole whose login tokens use this policy
bao write auth/approle/role/app token_policies=app token_ttl=1h token_max_ttl=24h

# 3. Read role_id and secret_id and distribute them to the application
bao read -field=role_id auth/approle/role/app/role-id
bao write -f -field=secret_id auth/approle/role/app/secret-id

role_id acts as a username and secret_id as a password. Applications exchange them for a short-lived token, then use that token to access secrets:

bao write auth/approle/login role_id=<role_id> secret_id=<secret_id>

Deliver secret_id through a secure channel. Restrict credentials further with secret_id_ttl, secret_id_num_uses, and token_bound_cidrs as needed.

Through the VIP, HAProxy forwards in TCP mode, so OpenBao sees the VAULT member’s address rather than the original client. Audit logs record that member address, and token_bound_cidrs set to client networks will reject these requests.

HTTP API

Clients without bao can call the HTTP API directly. For example, log in with AppRole and read a secret:

CA=/etc/pki/ca.crt
URL=https://vault.pigsty:8200

# Log in with AppRole to obtain a client token
TOKEN=$(curl -s --cacert $CA -X POST $URL/v1/auth/approle/login \
  -d '{"role_id":"<role_id>","secret_id":"<secret_id>"}' | jq -r .auth.client_token)

# Read a KV v2 secret; note data/ in the path
curl -s --cacert $CA -H "X-Vault-Token: $TOKEN" $URL/v1/secret/data/app/db | jq .data.data

Unauthenticated endpoints support health checks and monitoring:

curl -s --cacert /etc/pki/ca.crt https://vault.pigsty:8200/v1/sys/health     # Health status
curl -s --cacert /etc/pki/ca.crt https://vault.pigsty:8200/v1/sys/leader     # Active member

Reserved Paths

These paths and names are used by Pigsty or reserved for future features; do not use them for applications:

Path / Name	Purpose
`tde/<pg_cluster>`	Reserved for PGSQL `pg_tde` keys, KV v2, one per PG cluster
`kes/<minio_cluster>`	Reserved for MINIO KES keys, KV v2, one per object-storage cluster
`tde-`, `kes-` policies	Reserved for those consumers
`vault-backup` policy	Backup token; read-only access to `sys/storage/raft/snapshot`

Before whole-cluster removal, vault-rm.yml lists existing tde/* and kes/* mounts to identify consumers that will permanently lose keys.