ansible-lemp-wordpress/docs/vault.md

Ansible Vault Security Guide

This guide explains how to use Ansible Vault to securely manage passwords and sensitive data in your WordPress deployment.

What is Ansible Vault?

Ansible Vault is a feature that allows you to encrypt sensitive data like passwords, API keys, and certificates, so they can be safely stored in version control systems like Git.

Why Use Ansible Vault?

Without Vault (Insecure):

# production.yml - INSECURE!
mysql_root_password: "my-secret-password"  # Visible to everyone

With Vault (Secure):

# production.yml - SECURE!
mysql_root_password: "{{ vault_mysql_root_password }}"  # References encrypted value

# group_vars/all/vault.yml - ENCRYPTED!
$ANSIBLE_VAULT;1.1;AES256
66633030613...  # Encrypted content

Quick Setup Guide

1. Create the Vault Structure

# Create directories
mkdir -p group_vars/all/

# Create encrypted vault file
ansible-vault create group_vars/all/vault.yml

You'll be prompted to enter a vault password. Remember this password!

2. Add Encrypted Passwords

In the vault editor, add your sensitive data:

# Content of group_vars/all/vault.yml (will be encrypted)
vault_mysql_root_password: "your-super-secure-mysql-password"
vault_wordpress_db_password: "your-secure-wp-db-password"
vault_wp_admin_password: "your-secure-admin-password"

3. Update Your Inventory

Modify your inventory/production.yml to reference vault variables:

wordpress_servers:
  hosts:
    your-server.example.com:
      # ... other settings ...
      
      # Database - Using vault variables
      mysql_root_password: "{{ vault_mysql_root_password }}"
      wordpress_db_password: "{{ vault_wordpress_db_password }}"
      
      # WordPress Admin - Using vault variables  
      wp_admin_password: "{{ vault_wp_admin_password }}"

4. Deploy with Vault

# Deploy and provide vault password
ansible-playbook -i inventory/production.yml playbooks/lemp-wordpress.yml --ask-vault-pass

# Or store vault password in a file (keep secure!)
echo "your-vault-password" > .vault_password
chmod 600 .vault_password
ansible-playbook -i inventory/production.yml playbooks/lemp-wordpress.yml --vault-password-file .vault_password

Vault File Management

View Encrypted Content

ansible-vault view group_vars/all/vault.yml

Edit Encrypted Content

ansible-vault edit group_vars/all/vault.yml

Change Vault Password

ansible-vault rekey group_vars/all/vault.yml

Encrypt Existing File

ansible-vault encrypt group_vars/all/vault.yml

Decrypt File (Temporarily)

ansible-vault decrypt group_vars/all/vault.yml
# Edit the file
ansible-vault encrypt group_vars/all/vault.yml

Complete Example

Project Structure

ansible-lemp-wordpress/
├── inventory/
│   └── production.yml          # References vault variables
├── group_vars/
│   └── all/
│       └── vault.yml           # Encrypted passwords
├── playbooks/
│   └── lemp-wordpress.yml
└── .vault_password             # Optional: vault password file

Example Vault File

# group_vars/all/vault.yml (encrypted)
vault_mysql_root_password: "MySecure123!@#Root"
vault_wordpress_db_password: "WordPressDB456$%^"
vault_wp_admin_password: "AdminPass789&*()"
vault_ssl_email: "admin@yourcompany.com"

Example Inventory

# inventory/production.yml
wordpress_servers:
  hosts:
    web1.yourcompany.com:
      ansible_host: 192.168.1.100
      ansible_user: ubuntu
      domain_name: yoursite.com
      
      # SSL Configuration
      ssl_enabled: true
      ssl_email: "{{ vault_ssl_email }}"
      
      # Database (using vault)
      mysql_root_password: "{{ vault_mysql_root_password }}"
      wordpress_db_name: "wordpress"
      wordpress_db_user: "wp_user"
      wordpress_db_password: "{{ vault_wordpress_db_password }}"
      
      # WordPress Admin (using vault)
      wp_admin_user: "admin"
      wp_admin_password: "{{ vault_wp_admin_password }}"
      wp_admin_email: "{{ vault_ssl_email }}"
      wp_site_title: "My Company Website"

Security Best Practices

1. Vault Password Management

• Never commit the vault password to Git
• Use a strong, unique password for your vault
• Consider using a password manager
• For teams, use external secret management systems

2. File Permissions

# Secure vault password file
chmod 600 .vault_password

# Add to .gitignore
echo ".vault_password" >> .gitignore

3. Git Configuration

# Add vault file to Git (it's encrypted, so it's safe)
git add group_vars/all/vault.yml

# But never add the password file
echo ".vault_password" >> .gitignore
git add .gitignore

4. Team Collaboration

For teams, consider these approaches:

Option 1: Shared Vault Password

• Share vault password through secure channels (encrypted email, password manager)
• Each team member stores password locally

Option 2: External Secret Management

• Use HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault
• Ansible can integrate with these systems

Deployment Commands

Basic Deployment

# Standard deployment with vault
ansible-playbook -i inventory/production.yml playbooks/lemp-wordpress.yml --ask-vault-pass

Ultimate Performance Deployment

# Ultimate deployment with vault
ansible-playbook -i inventory/production.yml playbooks/lemp-wordpress-ultimate.yml --ask-vault-pass

Using Password File

# With password file (for automation)
ansible-playbook -i inventory/production.yml playbooks/lemp-wordpress.yml --vault-password-file .vault_password

Troubleshooting

"Decryption failed" Error

• Check that you're using the correct vault password
• Verify the vault file isn't corrupted: ansible-vault view group_vars/all/vault.yml

"Variable not found" Error

• Ensure vault variables are properly referenced in inventory
• Check variable names match exactly (case sensitive)
• Verify vault file is in the correct location

Permission Denied

• Check file permissions: ls -la group_vars/all/vault.yml
• Ensure Ansible can read the vault file

Migration from Plain Text

If you have existing plain text passwords in your inventory:

1. Create vault file:

ansible-vault create group_vars/all/vault.yml

2. Move passwords to vault:

# Add to vault.yml
vault_mysql_root_password: "your-existing-password"

3. Update inventory:

# Change in production.yml
mysql_root_password: "{{ vault_mysql_root_password }}"

4. Test deployment:

ansible-playbook -i inventory/production.yml playbooks/lemp-wordpress.yml --ask-vault-pass --check

Conclusion

Ansible Vault provides a secure way to manage sensitive data while keeping it version-controlled. While it adds complexity, it's essential for production deployments where security is paramount.

For simple testing or development, plain text passwords in inventory files may be acceptable, but always use Vault for production environments.

---

Next Steps:

• Production Deployment Guide
• SSL Setup Guide
• Security Best Practices