c7a300b922
Some checks failed
CI / lint-and-test (pull_request) Successful in 1m21s
CI / ansible-validation (pull_request) Successful in 9m3s
CI / secret-scanning (pull_request) Successful in 3m19s
CI / dependency-scan (pull_request) Successful in 7m13s
CI / sast-scan (pull_request) Successful in 6m38s
CI / license-check (pull_request) Successful in 1m16s
CI / vault-check (pull_request) Failing after 6m40s
CI / playbook-test (pull_request) Successful in 9m28s
CI / container-scan (pull_request) Successful in 7m59s
CI / sonar-analysis (pull_request) Failing after 1m11s
CI / workflow-summary (pull_request) Successful in 1m11s
- Add roles/pote: Python/venv deployment role with PostgreSQL, cron jobs - Add playbooks/app/: Proxmox app stack provisioning and configuration - Add roles/app_setup: Generic app deployment role (Node.js/systemd) - Add roles/base_os: Base OS hardening role - Enhance roles/proxmox_vm: Split LXC/KVM tasks, improve error handling - Add IP uniqueness validation: Preflight check for duplicate IPs within projects - Add Proxmox-side IP conflict detection: Check existing LXC net0 configs - Update inventories/production/group_vars/all/main.yml: Add pote project config - Add vault.example.yml: Template for POTE secrets (git key, DB, SMTP) - Update .gitignore: Exclude deploy keys, backup files, and other secrets - Update documentation: README, role docs, execution flow guides Security: - All secrets stored in encrypted vault.yml (never committed in plaintext) - Deploy keys excluded via .gitignore - IP conflict guardrails prevent accidental duplicate IP assignments
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 |