ansible/docs/guides/vault.md

Ansible Vault Guide

Ansible Vault encrypts sensitive data like passwords and API keys while keeping them usable in playbooks.

Quick Start

Create Vault

make create-vault

Add Secrets

When editor opens, add your secrets:

---
# Authentication Keys
vault_tailscale_auth_key: "tskey-auth-..."
vault_proxmox_password: "super-secret"

# API Keys
vault_github_token: "ghp_..."
vault_docker_hub_token: "dckr_..."

# Passwords
vault_db_password: "complex-password"
vault_vm_cipassword: "vm-user-password"

# SSH Keys
vault_ssh_public_key: "ssh-ed25519 AAAA..."

Use in Playbooks

Reference vault variables with {{ vault_variable_name }}:

tailscale_auth_key: "{{ vault_tailscale_auth_key }}"
database_password: "{{ vault_db_password }}"

File Structure

group_vars/
├── all.yml                 # Plain text configuration
└── all/
    └── vault.yml          # Encrypted secrets (created by make create-vault)

host_vars/
├── dev01.yml              # Host-specific plain text
└── dev01/
    └── vault.yml          # Host-specific secrets

Common Commands

# Create new vault
make create-vault

# Edit existing vault
make edit-vault              # Global vault
make edit-vault HOST=dev01   # Host-specific vault

# View decrypted contents
ansible-vault view group_vars/all/vault.yml

# Change vault password
ansible-vault rekey group_vars/all/vault.yml

Password Management

Option 1: Password File (Recommended for Automation)

echo "your-vault-password" > ~/.ansible-vault-pass
chmod 600 ~/.ansible-vault-pass

Option 2: Interactive (More Secure)

Add --ask-vault-pass to commands or let Makefile handle it.

Best Practices

What to Encrypt

✅ Put in Vault:

• API keys and tokens
• Passwords and passphrases
• Private keys and certificates
• Database credentials
• Any sensitive configuration

❌ Keep in Plain Text:

• Non-sensitive configuration
• Default settings
• Public information
• Documentation

Naming Convention

Prefix vault variables with vault_ for clarity:

• vault_db_password → encrypted in vault
• db_host → plain text in all.yml

Security Tips

1. Never commit unencrypted secrets
2. Use different vault passwords per environment
3. Rotate vault passwords periodically
4. Limit vault file access (chmod 600)
5. Use git-crypt or similar for additional protection

Troubleshooting

"Attempting to decrypt but no vault secrets found"

• Ensure vault password file exists: ~/.ansible-vault-pass
• Check file permissions: chmod 600 ~/.ansible-vault-pass

"ERROR! Decryption failed"

• Wrong password - verify vault password
• Corrupted vault file - recreate from secure storage

Variables not being replaced

• Check variable naming matches exactly
• Ensure vault file is in correct location
• Verify vault file is properly encrypted

Related Documentation

• Tailscale Setup - Uses vault for auth keys
• Security Best Practices - Overall security guidelines