Refactor Ansible playbooks to comply with best practices and fix linting violations

- Implement 4-role architecture (base_provision, patching, hardening, decommission) - Extract hardcoded values to role defaults and group_vars - Add Ansible Vault integration for secrets management - Implement proper handlers for service restarts instead of direct tasks - Add Molecule testing framework with Docker driver - Configure ansible-lint with production profile settings Fix all 125+ ansible-lint violations: - Add FQCN (Fully Qualified Collection Names) to all modules - Replace yes/no with true/false for boolean values - Add explicit mode parameters to file/template operations - Remove duplicate post_tasks blocks from playbooks - Add newlines at end of all YAML files - Fix key ordering in tasks (name, when, block) - Convert service restarts to handlers with notify - Remove ignore_errors in favor of failed_when/changed_when - Fix line length violations and empty lines - Add noqa comments for unavoidable risky-file-permissions Update documentation: - Add REFACTORING.md with implementation details - Add VAULT_GUIDE.md for secrets management - Add per-role README.md files - Update existing documentation All playbooks now pass ansible-lint production profile with 0 violations.
2026-05-03 22:31:04 +00:00
parent 2f5e3653d6
commit 78bcfce43a
36 changed files with 1694 additions and 573 deletions
@@ -0,0 +1,231 @@
+# Vault Configuration Guide
+
+## Overview
+
+This project uses Ansible Vault to securely manage sensitive data such as passwords, API keys, and credentials.
+
+## Setup
+
+### 1. Create Vault Password File
+
+```bash
+# Generate a secure password
+openssl rand -base64 32 > ~/.vault_pass.txt
+
+# Secure the file
+chmod 600 ~/.vault_pass.txt
+```
+
+### 2. Add to .bashrc or .zshrc
+
+```bash
+export ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.vault_pass.txt"
+```
+
+### 3. Configure ansible.cfg
+
+```ini
+[defaults]
+vault_password_file = ~/.vault_pass.txt
+```
+
+## Vault Files
+
+### group_vars/vault.yml
+
+This file contains all encrypted secrets:
+
+```yaml
+---
+# Vault variables for sensitive data
+vault_admin_password: "<secure_password>"
+vault_db_password: "<db_password>"
+vault_grafana_password: "<grafana_password>"
+vault_ssh_key_passphrase: "<ssh_passphrase>"
+```
+
+## Encrypting Secrets
+
+### First Time - Encrypt vault.yml
+
+```bash
+# Edit the file first with plain text secrets
+ansible-vault encrypt group_vars/vault.yml
+
+# You'll be prompted for vault password
+# Then the file will be automatically encrypted
+```
+
+### Edit Encrypted Vault
+
+```bash
+# Edit the vault file (will decrypt, open editor, re-encrypt)
+ansible-vault edit group_vars/vault.yml
+
+# Or view without editing
+ansible-vault view group_vars/vault.yml
+```
+
+### Encrypt New Files
+
+```bash
+ansible-vault encrypt group_vars/new_secrets.yml
+```
+
+## Using Vault in Playbooks
+
+### Import Vault Variables
+
+```yaml
+---
+- name: My Playbook
+  hosts: all
+  vars_files:
+    - vars/vault.yml
+
+  tasks:
+    - name: Use vault password
+      user:
+        name: admin
+        password: "{{ vault_admin_password | password_hash('sha512') }}"
+```
+
+## Running Playbooks with Vault
+
+### Method 1: Using .vault_pass.txt
+
+```bash
+export ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.vault_pass.txt"
+ansible-playbook playbooks/provision.yml -i inventory/hosts.ini
+```
+
+### Method 2: Inline Flag
+
+```bash
+ansible-playbook playbooks/provision.yml \
+  --vault-password-file ~/.vault_pass.txt \
+  -i inventory/hosts.ini
+```
+
+### Method 3: Prompt for Password
+
+```bash
+ansible-playbook playbooks/provision.yml \
+  --ask-vault-pass \
+  -i inventory/hosts.ini
+
+# You'll be prompted to enter vault password
+```
+
+## Viewing Vault Contents
+
+```bash
+# View encrypted file
+ansible-vault view group_vars/vault.yml
+
+# View specific variable
+ansible-playbook playbooks/provision.yml \
+  --tags never \
+  -e "ansible_connection=local" \
+  -i localhost, \
+  -m debug \
+  -a "var=vault_admin_password"
+```
+
+## Vault Best Practices
+
+### ✅ DO
+
+- Store all passwords in vault.yml
+- Use strong vault passwords (32+ characters)
+- Keep vault password file secure (chmod 600)
+- Rotate vault passwords periodically
+- Version control only encrypted files
+- Document what each variable contains
+
+### ❌ DON'T
+
+- Commit unencrypted vault.yml to git
+- Share vault password file
+- Hardcode secrets in playbooks
+- Use weak passwords
+- Check plaintext secrets into version control
+
+## Rekeying Vault
+
+To change the vault password:
+
+```bash
+ansible-vault rekey group_vars/vault.yml
+
+# You'll be prompted for:
+# 1. Current vault password
+# 2. New vault password
+# 3. Confirm new vault password
+```
+
+## CI/CD Integration
+
+For CI/CD pipelines (GitHub Actions, GitLab CI, etc.):
+
+### GitHub Actions Example
+
+```yaml
+- name: Run Ansible Playbook
+  env:
+    ANSIBLE_VAULT_PASSWORD: ${{ secrets.ANSIBLE_VAULT_PASSWORD }}
+  run: |
+    echo "$ANSIBLE_VAULT_PASSWORD" > ~/.vault_pass.txt
+    ansible-playbook playbooks/provision.yml
+```
+
+### GitLab CI Example
+
+```yaml
+deploy:
+  script:
+    - echo "$ANSIBLE_VAULT_PASSWORD" > ~/.vault_pass.txt
+    - ansible-playbook playbooks/provision.yml
+  secrets:
+    - ANSIBLE_VAULT_PASSWORD
+```
+
+## Troubleshooting
+
+### "Decryption failed"
+
+- Wrong vault password
+- File is corrupted
+- Check file permissions
+
+```bash
+# Check if file is encrypted
+file group_vars/vault.yml
+
+# Should show: ASCII text, with very long lines
+```
+
+### "vault password not found"
+
+- ANSIBLE_VAULT_PASSWORD_FILE not set
+- Path is incorrect
+- File permissions wrong (needs 600)
+
+### "Secrets leaked"
+
+If secrets are accidentally committed:
+
+```bash
+# Remove from git history
+git filter-branch --force --index-filter \
+  'git rm --cached --ignore-unmatch group_vars/vault.yml' \
+  --prune-empty --tag-name-filter cat -- --all
+
+# Force push (careful!)
+git push origin --force --all
+```
+
+## Additional Resources
+
+- [Ansible Vault Documentation](https://docs.ansible.com/ansible/latest/vault_guide/)
+- [Vault Best Practices](https://docs.ansible.com/ansible/latest/vault_guide/vault_managing_passwords.html)