125 lines
3.0 KiB
Markdown
125 lines
3.0 KiB
Markdown
# Ansible Vault Guide
|
|
|
|
Ansible Vault encrypts sensitive data like passwords and API keys while keeping them usable in playbooks.
|
|
|
|
## Quick Start
|
|
|
|
### Create Vault
|
|
```bash
|
|
make create-vault
|
|
```
|
|
|
|
### Add Secrets
|
|
When editor opens, add your secrets:
|
|
```yaml
|
|
---
|
|
# 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 }}`:
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
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](./tailscale.md) - Uses vault for auth keys
|
|
- [Security Best Practices](../reference/security.md) - Overall security guidelines |