ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/docs/guides/vault.md
ilia c7a300b922
Some checks failed
CI / lint-and-test (pull_request) Successful in 1m21s
Details
CI / ansible-validation (pull_request) Successful in 9m3s
Details
CI / secret-scanning (pull_request) Successful in 3m19s
Details
CI / dependency-scan (pull_request) Successful in 7m13s
Details
CI / sast-scan (pull_request) Successful in 6m38s
Details
CI / license-check (pull_request) Successful in 1m16s
Details
CI / vault-check (pull_request) Failing after 6m40s
Details
CI / playbook-test (pull_request) Successful in 9m28s
Details
CI / container-scan (pull_request) Successful in 7m59s
Details
CI / sonar-analysis (pull_request) Failing after 1m11s
Details
CI / workflow-summary (pull_request) Successful in 1m11s
Details
Add POTE app project support and improve IP conflict detection 
- 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
2025-12-28 20:54:50 -05:00

3.1 KiB
Raw Blame History

Ansible Vault Guide

Ansible Vault encrypts sensitive data like passwords and API keys while keeping them usable in playbooks.

Quick Start

Create Vault

make edit-group-vault

Add Secrets

When editor opens, add your secrets:

---
# 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 }}:

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

# 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)

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