Vault

---
name: vault
description: "Expert agent for HashiCorp Vault across all editions (Community, Enterprise, HCP). Covers seal/unseal, secret engines (KV, database, PKI, transit), auth methods (AppRole, Kubernetes, OIDC, AWS), policies, Vault Agent, Vault Secrets Operator, and replication. WHEN: \"HashiCorp Vault\", \"Vault seal\", \"Vault unseal\", \"secret engine\", \"AppRole\", \"Vault Agent\", \"Vault Operator\", \"VSO\", \"transit encryption\", \"Vault PKI\"."
license: MIT
---

# HashiCorp Vault

This skill covers HashiCorp Vault across all editions: Community (BSL 1.1), Enterprise, and HCP Vault Dedicated. It has deep knowledge of Vault's architecture, operational patterns, secret engines, auth methods, and Kubernetes integrations.

> **Note**: HCP Vault Secrets (the SaaS key-value store) reaches end-of-life July 2026. Migration path is HCP Vault Dedicated or self-managed Vault.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Operations** (seal, unseal, backup, upgrade) — Apply operational knowledge below
   - **Secret engine** — Load `references/best-practices.md` for engine-specific patterns
   - **Auth method** — Apply auth method knowledge below
   - **Policy/RBAC** — Apply policy knowledge below
   - **Architecture/HA** — Load `references/architecture.md`
   - **Kubernetes integration** — Apply VSO/Vault Agent/CSI knowledge below
   - **Performance troubleshooting** — Load `references/architecture.md`

2. **Identify edition** — Community vs. Enterprise (namespaces, replication, Sentinel policies, HSM auto-unseal, FIPS) vs. HCP Vault Dedicated.

3. **Load context** — Read the appropriate reference file for deep knowledge.

4. **Provide specific guidance** — Include CLI commands, API calls, and HCL policy examples.

## Core Architecture

### Vault Components

```
┌──────────────────────────────────────────────────────┐
│                    Vault Server                        │
│  ┌─────────────────────────────────────────────────┐ │
│  │  Barrier (AES-256-GCM encryption)               │ │
│  │  Everything inside is encrypted at rest         │ │
│  │  ┌─────────────┐  ┌────────────────────────┐   │ │
│  │  │ Secret       │  │ Auth Methods           │   │ │
│  │  │ Engines      │  │ (token, LDAP, OIDC...) │   │ │
│  │  └─────────────┘  └────────────────────────┘   │ │
│  │  ┌─────────────┐  ┌────────────────────────┐   │ │
│  │  │ Audit        │  │ Policies (HCL)         │   │ │
│  │  │ Devices      │  │                        │   │ │
│  │  └─────────────┘  └────────────────────────┘   │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────┐ │
│  │  Storage Backend (Raft / Consul / S3 / etc.)    │ │
│  └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```

### Seal and Unseal

Vault encrypts all data with a root key. On startup, Vault is **sealed** — the root key is not in memory, and no operations are possible except unseal.

**Shamir's Secret Sharing (default)**:
- Root key is split into N shares; K shares required to reconstruct it (default: 5 shares, 3 required)
- Each key holder provides their share; when threshold met, Vault unseals
- Shares are provided by operators via CLI, API, or UI

```bash
# Check seal status
vault status

# Provide an unseal key (repeat K times with different keys)
vault operator unseal <key-share>

# Initialize new Vault (generates root key + initial root token)
vault operator init -key-shares=5 -key-threshold=3
```

**Auto-Unseal** (Enterprise + Community 1.4+):
Vault delegates root key protection to an external KMS:
- AWS KMS (`awskms` seal)
- Azure Key Vault (`azurekeyvault` seal)
- GCP Cloud KMS (`gcpckms` seal)
- OCI KMS (`ocikms` seal)
- HSM via PKCS#11 (`pkcs11` seal — Enterprise only)

```hcl
# vault.hcl — AWS KMS auto-unseal
seal "awskms" {
  region     = "us-east-1"
  kms_key_id = "alias/vault-unseal"
}
```

**Seal Migration**: Can migrate between Shamir and auto-unseal, or between two auto-unseal providers, using `vault operator unseal -migrate`.

### Storage Backends

| Backend | Use When | Notes |
|---|---|---|
| **Raft (Integrated Storage)** | Recommended default | Built-in HA, no external dependency, WAL-based |
| Consul | Legacy deployments | Still supported; adds operational overhead |
| S3 | Non-HA single node | No built-in HA; use auto-unseal |
| Azure Blob | Azure deployments | Non-HA |
| GCS | GCP deployments | Non-HA |
| In-Memory | Dev mode only | `vault server -dev` |

Raft is the recommended backend for all new deployments. It provides integrated HA without an external Consul cluster.

```hcl
# vault.hcl — Raft storage
storage "raft" {
  path    = "/vault/data"
  node_id = "vault-1"
}

# HA with Raft
ha_storage "raft" {
  path    = "/vault/data"
  node_id = "vault-1"
}
```

## Secret Engines

Enable, configure, and use secret engines. Each engine is mounted at a path.

```bash
# Enable a secret engine
vault secrets enable -path=secret kv-v2
vault secrets enable database
vault secrets enable pki

# List enabled engines
vault secrets list
```

### KV v2 (Key-Value)

The most common engine. Versioned key-value store.

```bash
# Write a secret
vault kv put secret/myapp/config db_password="s3cr3t" api_key="abc123"

# Read a secret (latest version)
vault kv get secret/myapp/config

# Read specific version
vault kv get -version=2 secret/myapp/config

# Get metadata (all versions)
vault kv metadata get secret/myapp/config

# Delete (soft delete, version preserved)
vault kv delete secret/myapp/config

# Destroy (permanent, removes version data)
vault kv destroy -versions=1,2 secret/myapp/config

# Enable max versions (metadata)
vault kv metadata put -max-versions=10 secret/myapp/config
```

### Database Secret Engine

Generates dynamic credentials for databases. Credentials are created on-demand, have a TTL, and are automatically revoked when the lease expires.

```bash
vault secrets enable database

# Configure connection (PostgreSQL example)
vault write database/config/my-postgres \
    plugin_name=postgresql-database-plugin \
    connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb" \
    allowed_roles="app-role" \
    username="vault-admin" \
    password="vault-admin-pass"

# Create a role
vault write database/roles/app-role \
    db_name=my-postgres \
    creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
    default_ttl="1h" \
    max_ttl="24h"

# Generate credentials
vault read database/creds/app-role
# Returns: username=v-token-app-role-... password=...
```

Supported databases: PostgreSQL, MySQL/MariaDB, MSSQL, Oracle, MongoDB, Cassandra, Elasticsearch, Redis, Snowflake, and more.

### PKI Secret Engine

Full Certificate Authority built into Vault. Used for internal PKI, mTLS, and as an ACME CA. See `references/pki-engine.md` for the full root/intermediate CA setup, role creation, and certificate issuance commands.

### Transit Secret Engine

Encryption-as-a-service. Applications encrypt/decrypt without ever handling the key.

```bash
vault secrets enable transit

# Create a key
vault write -f transit/keys/my-key

# Encrypt
vault write transit/encrypt/my-key \
    plaintext=$(echo "my secret data" | base64)
# Returns: ciphertext=vault:v1:...

# Decrypt
vault write transit/decrypt/my-key \
    ciphertext="vault:v1:..."
# Returns: plaintext (base64 encoded)

# Rotate the key (old versions still available for decryption)
vault write -f transit/keys/my-key/rotate

# Rewrap ciphertext with latest key version
vault write transit/rewrap/my-key ciphertext="vault:v1:..."

# Configure minimum decryption version (retirement)
vault write transit/keys/my-key/config min_decryption_version=2
```

Key types: `aes256-gcm96` (default), `aes128-gcm96`, `chacha20-poly1305`, `rsa-2048`, `rsa-4096`, `ecdsa-p256`, `ed25519`.

### AWS, Azure, GCP Secret Engines

Generate cloud provider credentials on-demand:

```bash
# AWS — generates IAM user credentials or assumes roles
vault secrets enable aws
vault write aws/config/root access_key=... secret_key=... region=us-east-1
vault write aws/roles/my-role credential_type=assumed_role role_arns=arn:aws:iam::123:role/MyRole
vault read aws/creds/my-role  # Returns temp STS credentials
```

## Auth Methods

Applications prove their identity to Vault to receive a token.

### Token Auth (always enabled)

The root auth method. All other methods ultimately issue tokens.

```bash
# Create a token
vault token create -policy="my-policy" -ttl=24h

# Create periodic token (for long-running services)
vault token create -policy="my-policy" -period=24h

# Lookup token
vault token lookup

# Renew token
vault token renew
```

### AppRole Auth

Machine-to-machine auth without platform identity. Use when no cloud IAM or Kubernetes is available.

```bash
vault auth enable approle

vault write auth/approle/role/my-app \
    secret_id_ttl=10m \
    token_ttl=20m \
    token_max_ttl=30m \
    token_policies="my-app-policy"

# Get RoleID (not secret, can be baked into config)
vault read auth/approle/role/my-app/role-id

# Generate SecretID (treat like password — deliver via trusted mechanism)
vault write -f auth/approle/role/my-app/secret-id

# Login
vault write auth/approle/login role_id=<role-id> secret_id=<secret-id>
```

### Kubernetes Auth

Native auth for pods. Uses projected service account tokens.

```bash
vault auth enable kubernetes

vault write auth/kubernetes/config \
    kubernetes_host="https://kubernetes.default.svc" \
    kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

vault write auth/kubernetes/role/my-app \
    bound_service_account_names=my-sa \
    bound_service_account_namespaces=my-namespace \
    policies=my-app-policy \
    ttl=1h
```

### OIDC / JWT Auth

For human users via SSO (Okta, Azure AD, Google, etc.):

```bash
vault auth enable oidc

vault write auth/oidc/config \
    oidc_discovery_url="https://accounts.google.com" \
    oidc_client_id="..." \
    oidc_client_secret="..." \
    default_role="default"

vault write auth/oidc/role/default \
    bound_audiences="vault" \
    allowed_redirect_uris="https://vault.example.com/ui/vault/auth/oidc/oidc/callback" \
    user_claim="email" \
    policies="default"
```

### AWS IAM Auth

For EC2 instances and Lambda functions:

```bash
vault auth enable aws

vault write auth/aws/config/client \
    access_key=... \
    secret_key=...

vault write auth/aws/role/my-ec2-role \
    auth_type=iam \
    bound_iam_principal_arn=arn:aws:iam::123:role/MyRole \
    policies=my-policy \
    ttl=1h
```

## Policies

Policies control what a token can do. Written in HCL, path-based.

```hcl
# my-app-policy.hcl
# Read secrets for my-app
path "secret/data/myapp/*" {
  capabilities = ["read", "list"]
}

# Allow dynamic DB credentials
path "database/creds/app-role" {
  capabilities = ["read"]
}

# Allow PKI cert issuance
path "pki_int/issue/my-service" {
  capabilities = ["create", "update"]
}

# Allow token renewal (self)
path "auth/token/renew-self" {
  capabilities = ["update"]
}

# Deny access to all other paths (implicit default)
```

Capabilities: `create`, `read`, `update`, `delete`, `list`, `patch`, `deny`, `sudo`.

```bash
vault policy write my-app-policy my-app-policy.hcl
vault policy list
vault policy read my-app-policy
```

### Templated Policies

Use identity metadata in policies to avoid per-entity policies:

```hcl
# Auto-scoped per authenticated entity
path "secret/data/{{identity.entity.aliases.auth_kubernetes_abc123.metadata.service_account_name}}/*" {
  capabilities = ["read"]
}
```

## Vault Agent

Sidecar/daemon that handles auth, token renewal, and secret templating. Eliminates Vault auth logic from applications. See `references/vault-agent.md` for a full `vault-agent-config.hcl` example (auto_auth, template, cache, listener) and template syntax.

## Vault Secrets Operator (VSO)

Kubernetes Operator that syncs Vault secrets into Kubernetes Secrets and auto-rotates them. See `references/vso-examples.md` for full `VaultAuth`, `VaultStaticSecret`, and `VaultDynamicSecret` manifests.

## Audit Devices

Enable audit logging (required for compliance):

```bash
# Log to file
vault audit enable file file_path=/vault/logs/audit.log

# Log to syslog
vault audit enable syslog tag=vault facility=AUTH

# Log to socket
vault audit enable socket address=logstash:5000 socket_type=tcp

# List audit devices
vault audit list
```

Audit logs are HMAC-hashed (salted). Sensitive values are hashed, not plaintext. You can verify a value against the HMAC using `vault audit hash`.

## Enterprise Features

| Feature | Description |
|---|---|
| **Namespaces** | Multi-tenancy: isolated Vault environments within one cluster |
| **Performance Replication** | Read-only replica clusters for geo-distributed reads |
| **DR Replication** | Disaster recovery replica (active-passive) |
| **Sentinel Policies** | Fine-grained policy framework (EGP/RGP), request/response inspection |
| **MFA** | Step-up MFA for sensitive paths (TOTP, Okta, Duo, PingID) |
| **Control Groups** | Approval workflows: require N operators to approve sensitive actions |
| **HSM Auto-Unseal** | PKCS#11 HSM for root key protection |
| **FIPS 140-3** | FIPS-compliant build |

## Reference Files

Load these for deep knowledge on specific topics:

- `references/architecture.md` — Vault internals: storage engine, WAL, Raft consensus, replication internals, namespace architecture, plugin system, performance tuning, capacity planning.
- `references/best-practices.md` — Secret engine patterns, auth method selection guide, policy design, audit compliance, dynamic secrets patterns, PKI engine deployment, Transit engine usage, Vault Agent templates, VSO patterns.
- `references/pki-engine.md` — Full PKI secret engine walkthrough: root/intermediate CA generation, URL config, roles, and certificate issuance.
- `references/vault-agent.md` — Full Vault Agent HCL configuration example and template syntax.
- `references/vso-examples.md` — Full Vault Secrets Operator manifests (VaultAuth, VaultStaticSecret, VaultDynamicSecret).

## Diagnostic Scripts

Ready-made Vault status/audit scripts (read-only) in `scripts/`.

- `scripts/01-health-and-seal.sh` -- Seal status, HA leadership, health (the down-Vault triage)
- `scripts/02-auth-and-policy-audit.sh` -- Auth methods, mounts, and over-broad (sudo/wildcard) policies