ansible/VAULT_EXPLAINED.md

How Ansible Vault Works

The Problem:

You need to store secrets (like Tailscale auth keys) but don't want them visible in your code.

The Solution:

Ansible Vault encrypts files so secrets are hidden but still usable.

Here's how it works:

1. Create the encrypted vault file:

make create-vault

This creates group_vars/all/vault.yml (encrypted) and asks for a password.

2. Add your secrets to the vault:

When the editor opens, add:

---
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
vault_database_password: "super-secret-password"
vault_api_key: "another-secret"

3. Reference secrets in your code:

In any playbook or role, use:

tailscale_auth_key: "{{ vault_tailscale_auth_key }}"

File Structure:

group_vars/
├── all.yml                 # Plain text settings (everyone can see)
└── all/
    └── vault.yml           # Encrypted secrets (protected)

How Ansible finds the auth key:

1. Playbook runs → looks for tailscale_auth_key variable
2. Checks all.yml → finds reference to {{ vault_tailscale_auth_key }}
3. Checks all/vault.yml → finds the encrypted auth key
4. Decrypts and uses it → connects to Tailscale

Commands:

# Create new vault
make create-vault

# Edit existing vault  
ansible-vault edit group_vars/all/vault.yml

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

# Run playbooks (will ask for vault password)
make tailscale
# OR provide password file
ansible-playbook -i hosts tailscale-playbook.yml --vault-password-file ~/.vault_pass

No code changes needed!

The playbook already looks for vault_tailscale_auth_key - just put your real key in the vault and it works automatically.

What's NOT in the vault:

• Regular settings (in all.yml)
• Non-sensitive configuration
• Public information

What IS in the vault:

• Auth keys
• Passwords
• Private keys
• Any sensitive data