HashiCorp Vault — Hands-On Practical Guide

docker run --rm -it --cap-add=IPC_LOCK \
  -p 8200:8200 \
  --name vault-dev \
  hashicorp/vault:1.18 server -dev -dev-root-token-id=root

export VAULT_ADDR='http://localhost:8200'
export VAULT_TOKEN='root'

vault status

# Write a secret
vault kv put secret/my-app/database \
  username="app_user" \
  password="P@ssw0rd!2026" \
  host="postgres.internal" \
  port="5432"

# Read it back
vault kv get secret/my-app/database

# Read a specific field
vault kv get -field=password secret/my-app/database

# Check metadata (versions, created time, deletion time)
vault kv metadata get secret/my-app/database

# List versions
vault kv list secret/my-app/database

# Update the secret — this creates version 2
vault kv put secret/my-app/database password="NewP@ss!2026"

# Read specific version
vault kv get -version=1 secret/my-app/database
vault kv get -version=2 secret/my-app/database

# Undelete a deleted version
vault kv undelete -versions=1 secret/my-app/database

# Create a child token with a TTL
vault token create -ttl=24h -policy=default

# Use the child token
export VAULT_TOKEN="hvs.CAES..."
vault kv get secret/my-app/database

# Revoke the token when done
vault token revoke "hvs.CAES..."

# Enable userpass auth
vault auth enable userpass

# Create a user
vault write auth/userpass/users/alice \
  password="Password123!" \
  token_ttl="1h" \
  token_max_ttl="24h"

# Login returns a client token
vault login -method=userpass \
  username=alice \
  password=Password123!

vault kv get secret/my-app/database
# Error: 1 error occurred: permission denied

# Enable AppRole
vault auth enable approle

# Create a role
vault write auth/approle/role/my-app \
  secret_id_ttl="24h" \
  token_ttl="1h" \
  token_max_ttl="24h" \
  policies="default"

# Get the role_id and secret_id
vault read auth/approle/role/my-app/role-id
vault write -f auth/approle/role/my-app/secret-id

# Using the role_id and secret_id from above
vault write auth/approle/login \
  role_id="<role_id>" \
  secret_id="<secret_id>"

# Create separate KV engines
vault secrets enable -path=team-alpha -version=2 kv
vault secrets enable -path=team-beta -version=2 kv
vault secrets enable -path=shared -version=2 kv

# Write to each
vault kv put team-alpha/api-key key="a1b2c3"
vault kv put team-beta/api-key key="d4e5f6"
vault kv put shared/ca-certificate cert="-----BEGIN CERTIFICATE-----..."

# List all mounted engines
vault secrets list

# Soft delete (marks as deleted, keeps versions)
vault kv metadata delete shared/ca-certificate

# Restore soft-deleted secret
vault kv undelete -versions=1 shared/ca-certificate

# Permanent destroy (irrecoverable)
vault kv destroy -versions=1 shared/ca-certificate

# Hard destroy the entire secret (all versions)
vault kv metadata delete shared/ca-certificate
# You can still recover with: vault kv undelete
# To fully destroy:
vault kv metadata destroy shared/ca-certificate

# Enable CAS on the engine
vault secrets tune -cas-required=true team-alpha

# First write always succeeds
vault kv put team-alpha/config setting="value1"

# Second write WITHOUT CAS fails
vault kv put team-alpha/config setting="value2"
# Error: check-and-set parameter required

# Correct CAS write (must know current version)
vault kv put -cas=1 team-alpha/config setting="value2"

# Write a policy file
vault policy write team-alpha-admin - <<'EOF'
path "team-alpha/*" {
  capabilities = ["create", "read", "update", "delete", "list", "patch"]
}

path "team-alpha/metadata/*" {
  capabilities = ["list", "read", "delete"]
}

# Allow reading auth configuration
path "sys/auth" {
  capabilities = ["read", "list"]
}

# Allow renewing own token
path "auth/token/renew-self" {
  capabilities = ["update"]
}
EOF

# Write a read-only policy
vault policy write team-alpha-reader - <<'EOF'
path "team-alpha/data/*" {
  capabilities = ["read", "list"]
}

path "team-alpha/metadata/*" {
  capabilities = ["list", "read"]
}

# Allow looking up own token
path "auth/token/lookup-self" {
  capabilities = ["read"]
}
EOF

# List all policies
vault policy list

# Read a policy
vault policy read team-alpha-admin

# Assign to userpass user
vault write auth/userpass/users/alice \
  token_policies="team-alpha-reader"

# Assign to AppRole
vault write auth/approle/role/my-app \
  policies="team-alpha-reader"

# Login as Alice again and test
vault login -method=userpass username=alice password=Password123!
vault kv get team-alpha/api-key  # Should succeed
vault kv get secret/my-app/database  # Should fail (different path)

docker run -d --name postgres-vault \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=admin123 \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  postgres:16

# Enable the database secrets engine
vault secrets enable database

# Configure PostgreSQL connection
vault write database/config/myapp-pg \
  plugin_name="postgresql-database-plugin" \
  allowed_roles="myapp-role" \
  connection_url="postgresql://{{username}}:{{password}}@host.docker.internal:5432/myapp?sslmode=disable" \
  username="admin" \
  password="admin123"

# Create a role that generates credentials with specific SQL
vault write database/roles/myapp-role \
  db_name="myapp-pg" \
  creation_statements="CREATE USER \"{{name}}\" WITH PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
  default_ttl="1h" \
  max_ttl="24h"

# Generate fresh database credentials
vault read database/creds/myapp-role

# Test with the generated username/password
docker exec -it postgres-vault psql \
  -U "v-myapp-role-xyz123..." \
  -d myapp \
  -c "SELECT current_user, current_database();"

# View lease info
vault lease lookup database/creds/myapp-role/abc123...

# Explicitly revoke (before TTL expiry)
vault lease revoke database/creds/myapp-role/abc123...

# This will fail
docker exec -it postgres-vault psql -U "v-myapp-role-xyz123..." -d myapp -c "SELECT 1;"

# Enable PKI engine
vault secrets enable pki

# Tune lease to short-lived (Vault-issued certs should be short!)
vault secrets tune -max-lease-ttl=87600h pki  # 10 years for root CA

# Generate root CA certificate (self-signed)
vault write pki/root/generate/internal \
  common_name="mycompany.internal" \
  ttl=87600h

# Configure CRL and issuing endpoints
vault write pki/config/urls \
  issuing_certificates="http://localhost:8200/v1/pki/ca" \
  crl_distribution_points="http://localhost:8200/v1/pki/crl"

# Create a role for server certificates
vault write pki/roles/my-server \
  allowed_domains="mycompany.internal" \
  allow_subdomains=true \
  max_ttl="72h"

# Issue a certificate
vault write pki/issue/my-server \
  common_name="api.mycompany.internal" \
  ttl="24h"

# Initialize Vault (only on first node)
docker exec -it vault-1 vault operator init \
  -key-shares=5 \
  -key-threshold=3

# Output:
# Unseal Key 1: abc123...
# Unseal Key 2: def456...
# Unseal Key 3: ghi789...
# Unseal Key 4: jkl012...
# Unseal Key 5: mno345...
# Initial Root Token: hvs.xxxx...

# Unseal vault-1 (need 3 of 5 keys)
docker exec -it vault-1 vault operator unseal
# Enter Key 1
docker exec -it vault-1 vault operator unseal
# Enter Key 2
docker exec -it vault-1 vault operator unseal
# Enter Key 3

# Join vault-2 and vault-3 to the Raft cluster
docker exec -it vault-2 vault operator raft join http://vault-1:8200
docker exec -it vault-3 vault operator raft join http://vault-1:8200

# Unseal vault-2 and vault-3
docker exec -it vault-2 vault operator unseal
docker exec -it vault-2 vault operator unseal
docker exec -it vault-2 vault operator unseal
docker exec -it vault-3 vault operator unseal
docker exec -it vault-3 vault operator unseal
docker exec -it vault-3 vault operator unseal

# Verify cluster status
docker exec -it vault-1 vault operator raft list-peers

# Enable file audit
vault audit enable file file_path=/vault/logs/audit.log

# Enable syslog audit (for SIEM integration)
vault audit enable syslog \
  facility="AUTH" \
  tag="vault" \
  format="json"

# List audit devices
vault audit list

# View audit log (JSON lines — every request is logged)
docker exec vault-1 tail -f /vault/logs/audit.log | head -5

# 1. Enable and configure AppRole
vault auth enable approle

# 2. Enable database secrets
vault secrets enable database

# 3. Configure PostgreSQL
vault write database/config/myapp-pg \
  plugin_name="postgresql-database-plugin" \
  allowed_roles="myapp-role" \
  connection_url="postgresql://{{username}}:{{password}}@host.docker.internal:5432/myapp?sslmode=disable" \
  username="admin" \
  password="admin123"

# 4. Create database role with 30-minute TTL
vault write database/roles/myapp-role \
  db_name="myapp-pg" \
  creation_statements='CREATE USER "{{name}}" WITH PASSWORD '"'"'{{password}}'"'"' VALID UNTIL '"'"'{{expiration}}'"'"'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO "{{name}}";' \
  default_ttl="30m" \
  max_ttl="1h"

# 5. Create policy for the application
vault policy write myapp-policy - <<'EOF'
path "database/creds/myapp-role" {
  capabilities = ["read"]
}

path "secret/data/myapp/config" {
  capabilities = ["read"]
}
EOF

# 6. Create AppRole with the policy
vault write auth/approle/role/myapp-service \
  secret_id_ttl="24h" \
  token_ttl="1h" \
  policies="myapp-policy"

# 7. Get credentials for the application
ROLE_ID=$(vault read -field=role_id auth/approle/role/myapp-service/role-id)
SECRET_ID=$(vault write -f -field=secret_id auth/approle/role/myapp-service/secret-id)

echo "ROLE_ID=$ROLE_ID"
echo "SECRET_ID=$SECRET_ID"

# 8. Application authenticates and gets dynamic DB creds
APP_TOKEN=$(vault write -field=token auth/approle/login \
  role_id="$ROLE_ID" secret_id="$SECRET_ID")

vault read -address="$VAULT_ADDR" -token="$APP_TOKEN" database/creds/myapp-role

# Vault health endpoints
curl http://localhost:8200/v1/sys/health

# Returns:
# {
#   "initialized": true,
#   "sealed": false,
#   "standby": false,
#   "performance_standby": false,
#   "cluster_name": "vault-cluster",
#   "server_time_utc": 1718542381,
#   "version": "1.18.0"
# }

# Monitor with Prometheus
vault audit enable syslog tag="vault" facility="AUTH"
# Or enable Prometheus metrics endpoint
vault write sys/config/metrics enable=true

# Stop dev mode (Ctrl+C in the dev terminal, or)
docker stop vault-dev

# Stop production cluster
docker-compose -f vault-docker-compose.yml down -v

# Stop PostgreSQL
docker stop postgres-vault
docker rm postgres-vault