portfolio/enterprise-infra-simulator/VAULT_GUIDE.md

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

# 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

export ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.vault_pass.txt"

3. Configure ansible.cfg

[defaults]
vault_password_file = ~/.vault_pass.txt

Vault Files

group_vars/vault.yml

This file contains all encrypted secrets:

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

# 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

# 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

ansible-vault encrypt group_vars/new_secrets.yml

Using Vault in Playbooks

Import Vault Variables

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

export ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.vault_pass.txt"
ansible-playbook playbooks/provision.yml -i inventory/hosts.ini

Method 2: Inline Flag

ansible-playbook playbooks/provision.yml \
  --vault-password-file ~/.vault_pass.txt \
  -i inventory/hosts.ini

Method 3: Prompt for Password

ansible-playbook playbooks/provision.yml \
  --ask-vault-pass \
  -i inventory/hosts.ini

# You'll be prompted to enter vault password

Viewing Vault Contents

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

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

- 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

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

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

# 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
• Vault Best Practices