HashiCorp Vault: The Complete Guide to Secrets Management

HashiCorp Vault has become the industry standard for secrets management, providing a centralized solution for storing, accessing, and distributing sensitive data. Whether you're managing database credentials, API keys, certificates, or encryption keys, Vault provides the security controls and audit capabilities that modern infrastructure demands.

This comprehensive guide introduces Vault's core concepts and links to our detailed tutorials covering every aspect of Vault administration and usage.

What is HashiCorp Vault?

Vault is a tool for securely accessing secrets. A secret is anything you want to tightly control access to, such as:

Database credentials
API keys and tokens
SSH keys and certificates
Encryption keys
Passwords and passphrases

Vault provides a unified interface to any secret while providing tight access control and recording a detailed audit log.

Why Secrets Management Matters

Organizations without centralized secrets management face significant challenges:

Problem	Risk	Vault Solution
Secrets in code/config	Exposure in version control	Centralized, encrypted storage
Static credentials	No rotation, long-lived exposure	Dynamic secrets with TTL
No audit trail	Unknown who accessed what	Complete audit logging
Manual rotation	Human error, service disruption	Automated rotation
Broad access	Over-privileged users	Fine-grained policies

Who This Guide Is For

DevOps Engineers automating infrastructure and deployments
Security Teams implementing secrets management policies
Platform Engineers building self-service developer platforms
Developers integrating applications with secrets management
System Administrators managing credentials across environments

Vault Architecture Overview

Understanding Vault's architecture helps you make better decisions about deployment and usage.

┌─────────────────────────────────────────────────────────────────────────┐
│                         VAULT ARCHITECTURE                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐           │
│   │   Clients    │────▶│  Auth Methods │────▶│    Tokens    │           │
│   │  (CLI, API)  │     │ (LDAP, AppRole│     │  (Policies)  │           │
│   └──────────────┘     │  K8s, OIDC)   │     └──────────────┘           │
│                        └──────────────┘            │                     │
│                                                    │                     │
│                                                    ▼                     │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │                      VAULT CORE                              │      │
│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │      │
│   │  │   Policies  │  │    Audit    │  │   Secrets   │         │      │
│   │  │   Engine    │  │   Devices   │  │   Engines   │         │      │
│   │  └─────────────┘  └─────────────┘  └─────────────┘         │      │
│   └─────────────────────────────────────────────────────────────┘      │
│                                │                                         │
│                                ▼                                         │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │                    STORAGE BACKEND                           │      │
│   │         (Raft, Consul, S3, GCS, Azure, etc.)                │      │
│   └─────────────────────────────────────────────────────────────┘      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Core Components

Secrets Engines - Plugins that store, generate, or encrypt data:

KV (Key-Value) - Static secrets storage
Database - Dynamic database credentials
PKI - Certificate authority
Transit - Encryption as a service
AWS/GCP/Azure - Cloud credential generation

Auth Methods - Ways to prove identity to Vault:

Token - Direct token authentication
LDAP/Active Directory - Enterprise directory integration
OIDC - OAuth 2.0/OpenID Connect
AppRole - Machine/application authentication
Kubernetes - Pod identity

Policies - Rules defining what authenticated users can do:

Path-based access control
Capabilities: create, read, update, delete, list, sudo, deny
Written in HCL (HashiCorp Configuration Language)

Tokens - The core authentication unit:

All auth methods produce tokens
Tokens have policies attached
Tokens have TTL (time to live)
Tokens can create child tokens

The Seal/Unseal Mechanism

Vault uses a unique security model where the master encryption key is split using Shamir's Secret Sharing:

┌─────────────────────────────────────────────────────────────┐
│                      SEALED STATE                            │
│   • Encryption key NOT in memory                            │
│   • All data encrypted and inaccessible                     │
│   • Only status endpoint available                          │
└─────────────────────────────────────────────────────────────┘
                           │
                    Unseal Keys (3 of 5)
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     UNSEALED STATE                           │
│   • Encryption key loaded in memory                         │
│   • Secrets accessible (with proper auth)                   │
│   • Full API functionality                                  │
└─────────────────────────────────────────────────────────────┘

This means even if someone steals your storage backend, they cannot decrypt secrets without the unseal keys.

Getting Started

Installation

Vault can be installed via multiple methods:

# macOS
brew install vault

# Ubuntu/Debian
sudo apt update && sudo apt install vault

# RHEL/CentOS
sudo yum install vault

# Docker
docker run -d --name vault -p 8200:8200 hashicorp/vault

# Verify installation
vault version

For detailed installation instructions including GUI setup, see our Vault CLI Install Guide.

Development Mode Quick Start

For learning and testing (never use in production):

# Start dev server
vault server -dev

# In another terminal, set address
export VAULT_ADDR='http://127.0.0.1:8200'

# Dev mode prints a root token - set it
export VAULT_TOKEN='hvs.xxxxx'

# Verify connection
vault status

# Write your first secret
vault kv put secret/hello foo=world

# Read it back
vault kv get secret/hello

Development vs Production Mode

Feature	Dev Mode	Production Mode
Storage	In-memory	Persistent (Raft, Consul, etc.)
Unseal	Automatic	Manual or auto-unseal
TLS	Disabled	Required
Root token	Printed	Generated during init
Data persistence	None	Full
Use case	Testing/learning	Real workloads

Working with Secrets

The KV (Key-Value) secrets engine is the most commonly used for storing static secrets.

Basic Operations

# Write a secret
vault kv put secret/myapp username=admin password=secret

# Read the secret
vault kv get secret/myapp

# Read specific field
vault kv get -field=password secret/myapp

# List secrets at path
vault kv list secret/

# Delete (soft delete in v2)
vault kv delete secret/myapp

KV v1 vs KV v2

Feature	KV v1	KV v2
Versioning	No	Yes (default: 10 versions)
Soft delete	No	Yes
Metadata	No	Yes
Commands	`vault read/write`	`vault kv get/put`

Most deployments should use KV v2 for its versioning capabilities. Learn more in our KV v2 Secrets Engine Guide.

Secret Organization Best Practices

Organize secrets with hierarchical paths:

secret/
├── production/
│   ├── database/
│   │   ├── postgres
│   │   └── redis
│   ├── api/
│   │   ├── stripe
│   │   └── sendgrid
│   └── certificates/
│       └── tls
├── staging/
│   └── ...
└── shared/
    └── monitoring/
        └── datadog

For comprehensive secrets operations, see our Reading and Writing Secrets Guide.

Authentication and Access Control

Vault's security model separates authentication (who you are) from authorization (what you can do).

Authentication Methods

Choose auth methods based on the client type:

Client Type	Recommended Auth Method
Human users (SSO)	LDAP, OIDC
Human users (no SSO)	Userpass
CI/CD pipelines	AppRole
Kubernetes pods	Kubernetes auth
AWS workloads	AWS IAM auth
Automated scripts	AppRole or Certificate

# Enable an auth method
vault auth enable ldap

# Configure LDAP
vault write auth/ldap/config \
  url="ldap://ldap.example.com" \
  userdn="ou=Users,dc=example,dc=com" \
  groupdn="ou=Groups,dc=example,dc=com"

# Map LDAP group to Vault policy
vault write auth/ldap/groups/developers policies=dev-policy

For complete auth configuration, see our Authentication Methods Guide.

Policies and Authorization

Policies define what authenticated users can access:

# dev-policy.hcl - Read-only access to dev secrets
path "secret/data/development/*" {
  capabilities = ["read", "list"]
}

path "secret/metadata/development/*" {
  capabilities = ["read", "list"]
}

# Create policy
vault policy write dev-policy dev-policy.hcl

# Attach to auth method
vault write auth/ldap/groups/developers policies=dev-policy

Policy capabilities:

create - Create new data
read - Read existing data
update - Modify existing data
delete - Delete data
list - List keys at a path
sudo - Access root-protected paths
deny - Explicitly deny access (overrides other capabilities)

For comprehensive policy configuration, see our Policies and ACLs Guide.

Token Management

All auth methods ultimately produce tokens:

# View current token
vault token lookup

# Create a child token
vault token create -policy=dev-policy -ttl=1h

# Renew a token
vault token renew

# Revoke a token
vault token revoke <token>

Token properties:

TTL - How long until expiration
Max TTL - Maximum lifetime even with renewals
Policies - What the token can access
Orphan - Whether revocation cascades to children

Learn more in our Token Management Guide.

CI/CD and Automation

Automating secrets retrieval is critical for modern DevOps workflows.

AppRole Authentication

AppRole is designed specifically for machines and automated workflows:

┌─────────────────────────────────────────────────────────────┐
│                    AppRole Flow                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   role_id (embedded)  +  secret_id (delivered)  =  Token    │
│        │                       │                     │       │
│        ▼                       ▼                     ▼       │
│   Like a username        Like a password      Used for      │
│   Can be in config       Short-lived          API calls     │
│   Not sensitive alone    Rotate frequently                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

# Enable AppRole
vault auth enable approle

# Create a role
vault write auth/approle/role/jenkins-deploy \
  token_policies="ci-policy" \
  token_ttl=20m \
  secret_id_ttl=10m \
  secret_id_num_uses=1

# Get role_id (store in CI config)
vault read auth/approle/role/jenkins-deploy/role-id

# Generate secret_id (deliver securely)
vault write -f auth/approle/role/jenkins-deploy/secret-id

# Authenticate
vault write auth/approle/login \
  role_id="$ROLE_ID" \
  secret_id="$SECRET_ID"

CI/CD Integration Examples

GitHub Actions:

- uses: hashicorp/vault-action@v2
  with:
    url: https://vault.example.com
    method: approle
    roleId: ${{ secrets.VAULT_ROLE_ID }}
    secretId: ${{ secrets.VAULT_SECRET_ID }}
    secrets: |
      secret/data/production/db password | DB_PASSWORD

Jenkins Pipeline:

withVault(configuration: [vaultUrl: 'https://vault.example.com',
                          vaultCredentialId: 'vault-approle']) {
    def secrets = [
        [path: 'secret/data/production/db', secretValues: [
            [envVar: 'DB_PASSWORD', vaultKey: 'password']
        ]]
    ]
    // Use secrets in deployment
}

For complete CI/CD integration patterns, see our AppRole for CI/CD Guide.

Security Operations

Seal and Unseal Operations

Vault starts in a sealed state. Understanding seal operations is critical:

# Check seal status
vault status

# Unseal (repeat until threshold met)
vault operator unseal
# Enter unseal key when prompted

# Seal Vault (emergency or maintenance)
vault operator seal

When to seal Vault:

Security incident detected
Before major maintenance
Compliance audit requirements
Key holder compromise suspected

For complete seal/unseal procedures, see our Seal, Unseal, and Rekey Guide.

Rekeying

Rekeying generates new unseal keys, invalidating old ones:

# Start rekey operation
vault operator rekey -init -key-shares=5 -key-threshold=3

# Submit existing keys (repeat until threshold)
vault operator rekey

Rekey when:

Key holder leaves organization
Key compromise suspected
Changing key threshold
Annual key rotation policy

Root Token Management

Root tokens have unlimited access and should be used sparingly:

# Generate new root token (requires unseal keys)
vault operator generate-root -init
vault operator generate-root
# Repeat with unseal keys until complete

# Revoke root token when done
vault token revoke <root-token>

Best practice: Generate root tokens only when needed, complete the task, then revoke immediately.

For root token procedures, see our Root Token Regeneration Guide.

Auto-Unseal

For production, consider auto-unseal with cloud KMS:

# AWS KMS auto-unseal configuration
seal "awskms" {
  region     = "us-east-1"
  kms_key_id = "alias/vault-unseal-key"
}

Supported providers:

AWS KMS
Azure Key Vault
GCP Cloud KMS
HSM (Hardware Security Module)

Production Deployment

High Availability

Production Vault should run in HA mode:

┌─────────────────────────────────────────────────────────────┐
│                    Vault HA Cluster                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐            │
│   │  Active  │    │ Standby  │    │ Standby  │            │
│   │  Node    │◀──▶│  Node    │◀──▶│  Node    │            │
│   └──────────┘    └──────────┘    └──────────┘            │
│        │               │               │                    │
│        └───────────────┴───────────────┘                   │
│                        │                                    │
│                        ▼                                    │
│              ┌──────────────────┐                          │
│              │  Raft Storage    │                          │
│              │  (Integrated)    │                          │
│              └──────────────────┘                          │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Storage Backends

Backend	Use Case
Integrated Raft	Recommended for most deployments
Consul	Existing Consul infrastructure
S3/GCS/Azure Blob	Cloud-native deployments
PostgreSQL	Database-backed storage

Monitoring and Audit

Enable audit logging for compliance:

# File audit device
vault audit enable file file_path=/var/log/vault/audit.log

# Syslog audit device
vault audit enable syslog

Key metrics to monitor:

vault.core.unsealed - Seal status
vault.token.count - Active tokens
vault.expire.num_leases - Active leases
vault.runtime.gc_pause_ns - Performance

Backup and Recovery

Regular backups are essential:

# Raft snapshot
vault operator raft snapshot save backup.snap

# Restore from snapshot
vault operator raft snapshot restore backup.snap

Learning Path

Quick Reference: All Guides

Guide	Topic	Best For
CLI Install Guide	Installation and setup	New users
Reading & Writing Secrets	Basic CRUD operations	Daily usage
KV v2 Secrets Engine	Versioning, metadata	Storage deep-dive
Authentication Configuration	Auth methods setup	Access setup
Token Management	Token lifecycle	Security
Policies & ACLs	Authorization rules	Access control
AppRole for CI/CD	Pipeline integration	Automation
Seal, Unseal, Rekey	Security operations	Ops teams
Root Token Regeneration	Emergency access	Break-glass

Key Takeaways

Centralize secrets - Stop storing credentials in config files, environment variables, or code repositories
Use appropriate auth methods - Match authentication to client type (humans vs machines)
Apply least privilege - Grant minimum necessary access through fine-grained policies
Automate credential management - Use dynamic secrets and short TTLs where possible
Protect unseal keys - Distribute using Shamir shares, consider auto-unseal for operations
Enable audit logging - Maintain complete audit trail for compliance and security
Plan for production - HA deployment, proper backup strategy, monitoring

Next Steps

Start with our CLI Install Guide to set up Vault
Follow the learning path above for comprehensive understanding
Explore HashiCorp Learn for hands-on tutorials
Review Vault documentation for reference

For questions about implementing Vault in your organization, contact our team for expert guidance on secrets management strategy and deployment.