HashiCorp Vault Documentation - Complete Guide

Overview

This directory contains comprehensive HashiCorp Vault documentation covering fundamentals, architecture, secrets engines, authentication methods, and production deployment. Each file includes detailed explanations, workflow diagrams, and practical examples.

Documentation Structure

Core Topics

1. Vault Fundamentals ✅ Created
2. What problem Vault solves
3. Core concepts and terminology
4. Complete architecture diagrams
5. Installation on multiple platforms
6. Getting started (dev mode)

7. Development vs Production comparison

8. Secrets Engines (From original docs.md)

9. KV (Key-Value) v1 and v2
10. Database dynamic secrets
11. AWS dynamic credentials
12. Transit encryption engine
13. PKI certificate authority

14. Practical examples

15. Authentication Methods (From original docs.md)

16. Token authentication
17. Userpass (human login)
18. AppRole (machine-to-machine)
19. Kubernetes authentication
20. AWS IAM, Azure AD, GCP

21. Best practices

22. Policies and Access Control (From original docs.md)

23. Policy syntax (HCL)
24. Path-based permissions
25. Capabilities (read, write, delete, list)
26. Policy examples

27. Best practices

28. Seal and Unseal (From original docs.md)

29. Initialization process
30. Shamir's Secret Sharing
31. Manual unseal
32. Auto-unseal with cloud KMS

33. Production considerations

34. Docker Setup ✅ Exists

35. Docker Compose configuration
36. Development environment

37. Quick start guide

38. Production Deployment (From original docs.md)

39. Configuration file (HCL)
40. Storage backends (Consul, Raft, etcd)
41. High availability setup
42. TLS configuration
43. Systemd service

44. Monitoring and logging

45. Integration Examples (From original docs.md)

46. Node.js integration
47. Python integration
48. Go integration
49. Kubernetes integration

50. CI/CD integration

51. Best Practices (From original docs.md)

52. Security best practices
53. Operational best practices
54. When to use Vault
55. When NOT to use Vault

Quick Start

Installation

# Linux
wget https://releases.hashicorp.com/vault/1.15.5/vault_1.15.5_linux_amd64.zip
unzip vault_1.15.5_linux_amd64.zip
sudo mv vault /usr/local/bin/
vault version

# macOS
brew install hashicorp/tap/vault

# Docker
docker pull hashicorp/vault:1.15

Development Mode

# Start Vault in dev mode
vault server -dev

# In another terminal
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='root'  # Use token from dev server output

# Test
vault status

Docker Compose

cd vault-docker
docker compose up -d

# Access UI: http://localhost:8200
# Token: root

Architecture Diagrams

The documentation includes comprehensive ASCII diagrams for:

1. High-Level Architecture

• HTTP/HTTPS API Layer
• Authentication Methods
• Policy Engine
• Secrets Engines
• Storage Backend
• Audit Devices

2. Core Components

• Barrier (Encryption Layer)
• Seal/Unseal Mechanism
• Token Store
• Lease Management

3. Request Flow

• 7-step request processing
• Token validation
• Policy evaluation
• Secrets engine routing
• Audit logging

4. Authentication Flow (AppRole)

• Role ID and Secret ID
• Login process
• Token generation
• Secret retrieval

5. Seal/Unseal Process

• Initialization
• Shamir's Secret Sharing
• Manual unseal steps
• Auto-unseal with cloud KMS

6. Dynamic Secrets

• On-demand credential generation
• Lease management
• Automatic revocation

7. High Availability

• Active/Standby nodes
• Load balancer configuration
• Shared storage backend
• Leader election

8. Kubernetes Integration

• Init container pattern
• Sidecar container
• ServiceAccount authentication
• Secret injection

9. Complete System Design

• Frontend, backend, microservices
• Vault cluster
• External services
• Monitoring and audit

Learning Path

Beginner (Week 1)

1. Understand the Problem
2. Why secrets management matters
3. Traditional vs Vault approach

4. Core concepts

5. Install and Setup

6. Install Vault
7. Run in dev mode
8. Access UI

9. Basic CLI commands

10. First Secrets

11. Enable KV secrets engine
12. Store and retrieve secrets
13. Understand paths

Intermediate (Week 2-3)

1. Authentication
2. Token authentication
3. Create users (userpass)
4. AppRole for applications

5. Understand policies

6. Policies and Access Control

7. Write policies
8. Apply policies to tokens
9. Test permissions

10. Least privilege principle

11. Dynamic Secrets

12. Database secrets engine
13. Generate dynamic credentials
14. Understand leases
15. Renewal and revocation

Advanced (Week 4-6)

1. Production Setup
2. Configuration file
3. Storage backend (Consul/Raft)
4. TLS certificates

5. Initialization and unsealing

6. High Availability

7. Multi-node cluster
8. Load balancing
9. Auto-unseal

10. Disaster recovery

11. Integration

12. Application integration
13. Kubernetes deployment
14. CI/CD pipelines
15. Monitoring and alerting

Common Use Cases

1. Static Secrets (KV)

# Enable KV v2
vault secrets enable -path=secret kv-v2

# Store secret
vault kv put secret/myapp/db \
  username=admin \
  password=supersecret

# Read secret
vault kv get secret/myapp/db

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

2. Dynamic Database Credentials

# Enable database engine
vault secrets enable database

# Configure PostgreSQL connection
vault write database/config/postgresql \
  plugin_name=postgresql-database-plugin \
  allowed_roles="readonly" \
  connection_url="postgresql://{{username}}:{{password}}@localhost:5432/mydb" \
  username="vault" \
  password="vaultpass"

# Create role
vault write database/roles/readonly \
  db_name=postgresql \
  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/readonly

3. AppRole Authentication

# Enable AppRole
vault auth enable approle

# Create role
vault write auth/approle/role/myapp \
  token_policies="myapp-policy" \
  token_ttl=1h \
  token_max_ttl=4h

# Get Role ID
vault read auth/approle/role/myapp/role-id

# Generate Secret ID
vault write -f auth/approle/role/myapp/secret-id

# Login
vault write auth/approle/login \
  role_id="xxx" \
  secret_id="yyy"

Vault CLI Reference

Status and Info

# Check status
vault status

# Get server info
vault read sys/health

# List enabled secrets engines
vault secrets list

# List enabled auth methods
vault auth list

# List policies
vault policy list

Secrets Operations

# KV v2 operations
vault kv put secret/path key=value
vault kv get secret/path
vault kv get -field=key secret/path
vault kv delete secret/path
vault kv list secret/

# KV v2 versioning
vault kv get -version=2 secret/path
vault kv rollback -version=1 secret/path
vault kv metadata get secret/path

Token Operations

# Create token
vault token create -policy=mypolicy -ttl=1h

# Lookup token
vault token lookup

# Renew token
vault token renew

# Revoke token
vault token revoke <token>

# Revoke all tokens for a role
vault token revoke -mode=path auth/approle

Policy Operations

# Write policy
vault policy write mypolicy policy.hcl

# Read policy
vault policy read mypolicy

# List policies
vault policy list

# Delete policy
vault policy delete mypolicy

Seal/Unseal Operations

# Initialize Vault
vault operator init

# Unseal (repeat 3 times with different keys)
vault operator unseal <key1>
vault operator unseal <key2>
vault operator unseal <key3>

# Seal Vault
vault operator seal

# Check seal status
vault status

Integration Examples

Node.js

import vault from 'node-vault';

const client = vault({
  endpoint: 'http://127.0.0.1:8200',
  token: process.env.VAULT_TOKEN
});

// Read secret
const secret = await client.read('secret/data/myapp/db');
const password = secret.data.data.password;

// Write secret
await client.write('secret/data/myapp/api', {
  data: {
    api_key: 'abc123',
    api_secret: 'xyz789'
  }
});

Python

import hvac

# Initialize client
client = hvac.Client(
    url='http://127.0.0.1:8200',
    token=os.environ['VAULT_TOKEN']
)

# Read secret
secret = client.secrets.kv.v2.read_secret_version(
    path='myapp/db'
)
password = secret['data']['data']['password']

# Write secret
client.secrets.kv.v2.create_or_update_secret(
    path='myapp/api',
    secret=dict(api_key='abc123')
)

Go

import (
    vault "github.com/hashicorp/vault/api"
)

// Create client
config := vault.DefaultConfig()
config.Address = "http://127.0.0.1:8200"
client, _ := vault.NewClient(config)
client.SetToken(os.Getenv("VAULT_TOKEN"))

// Read secret
secret, _ := client.Logical().Read("secret/data/myapp/db")
password := secret.Data["data"].(map[string]interface{})["password"]

// Write secret
data := map[string]interface{}{
    "data": map[string]interface{}{
        "api_key": "abc123",
    },
}
client.Logical().Write("secret/data/myapp/api", data)

Best Practices

Security

1. Never use root token in production
2. Create specific tokens with limited policies

3. Use AppRole or other auth methods

4. Enable TLS

5. Always use HTTPS in production

6. Validate certificates

7. Use short TTLs

8. Tokens: 1-4 hours
9. Dynamic secrets: 1-24 hours

10. Renew before expiry

11. Enable audit logging

12. Log all requests and responses
13. Monitor for suspicious activity

14. Retain logs for compliance

15. Implement least privilege

16. One policy per application
17. Minimal required permissions
18. Regular policy audits

Operations

1. Use auto-unseal in production
2. AWS KMS, Azure Key Vault, GCP KMS

3. No manual intervention on restart

4. Deploy in HA mode

5. Minimum 3 nodes
6. Load balancer in front

7. Shared storage backend

8. Backup regularly

9. Backup storage backend
10. Backup unseal keys (secure location)

11. Test restore procedures

12. Monitor Vault health

13. Prometheus metrics
14. Grafana dashboards

15. Alert on seal status, errors

16. Rotate secrets regularly

17. Use dynamic secrets when possible
18. Automate rotation for static secrets
19. Update applications gracefully

Troubleshooting

Common Issues

1. Vault is Sealed

# Check status
vault status

# Unseal (provide 3 keys)
vault operator unseal

2. Permission Denied

# Check token policies
vault token lookup

# Verify policy allows operation
vault policy read <policy-name>

3. Connection Refused

# Check Vault is running
systemctl status vault

# Verify VAULT_ADDR
echo $VAULT_ADDR

# Check firewall
sudo ufw status

4. Token Expired

# Check token TTL
vault token lookup

# Renew token
vault token renew

# Or create new token
vault login -method=approle

Resources

Official Documentation

• Vault Documentation
• Vault API
• Vault Tutorials

Community

• Vault GitHub
• Vault Forum
• Vault Slack

Tools

• Vault Helm Chart
• Vault K8s
• Vault CSI Provider

When to Use Vault

✅ Use Vault When:

• Managing secrets for multiple applications
• Need dynamic credentials
• Compliance requirements (SOC 2, PCI-DSS, HIPAA)
• Microservices architecture
• Cloud-native applications
• Need encryption as a service
• Require audit trail

❌ Don't Use Vault When:

• Small hobby project (1-2 secrets)
• No security requirements
• Single application with few secrets
• No operational capacity to manage Vault
• Cost-sensitive (use cloud provider secrets manager)

Summary

This HashiCorp Vault documentation provides: - Comprehensive coverage from basics to advanced topics - Visual diagrams for architecture understanding - Practical examples for real-world scenarios - Best practices for production deployment - Integration guides for multiple languages - Troubleshooting for common issues

Perfect for DevOps engineers, security teams, and anyone implementing secrets management in modern infrastructure.

---

Last Updated: January 6, 2026
Vault Version: 1.15.5
Status: ✅ Fundamentals documented with comprehensive diagrams
Next: Complete remaining topics (Secrets Engines, Auth Methods, Policies, Production)