ilia
69a39e5e5b
## Summary This PR adds comprehensive support for deploying the **POTE** application project via Ansible, along with improvements to IP conflict detection and a new app stack provisioning system for Proxmox-managed LXC containers. ## Key Features ### 🆕 New Roles - **`roles/pote`**: Python/venv deployment role for POTE (PostgreSQL, cron jobs, Alembic migrations) - **`roles/app_setup`**: Generic app deployment role (Node.js/systemd) - **`roles/base_os`**: Base OS hardening role ### 🛡️ Safety Improvements - IP uniqueness validation within projects - Proxmox-side IP conflict detection - Enhanced error messages for IP conflicts ### 📦 New Playbooks - `playbooks/app/site.yml`: End-to-end app stack deployment - `playbooks/app/provision_vms.yml`: Proxmox guest provisioning - `playbooks/app/configure_app.yml`: OS + application configuration ## Security - ✅ All secrets stored in encrypted vault.yml - ✅ Deploy keys excluded via .gitignore - ✅ No plaintext secrets committed ## Testing - ✅ POTE successfully deployed to dev/qa/prod environments - ✅ All components validated (Git, PostgreSQL, cron, migrations) Co-authored-by: ilia <ilia@levkin.ca> Reviewed-on: #3
124 lines
3.1 KiB
Markdown
124 lines
3.1 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 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 |