# 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 edit-group-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
```
inventories/production/
├── group_vars/
│   └── all/
│       ├── main.yml       # Plain text configuration
│       └── vault.yml      # Encrypted secrets (edit with make edit-group-vault)
└── host_vars/
    ├── dev01.yml          # Host-specific plain text
    └── dev01/
        └── vault.yml      # Host-specific secrets (edit with make edit-vault HOST=dev01)
```

## Common Commands

```bash
# Edit group vault (production inventory)
make edit-group-vault

# Edit host-specific vault
make edit-vault HOST=dev01

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

# Change vault password
ansible-vault rekey inventories/production/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