# 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:
```bash
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:
```yaml
---
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:
```yaml
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:
```bash
# 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