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

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