How to Use Ansible Vault for Secret Management

How to Use Ansible Vault for Secret Management

Ansible Vault provides encryption for sensitive data such as passwords, API keys, and certificates within your Ansible projects. It lets you safely store secrets in version control alongside your playbooks without exposing them in plaintext.

Creating an Encrypted File

Use the ansible-vault create command to create a new encrypted secrets file:

# Create a new encrypted file
ansible-vault create group_vars/production/secrets.yml

# You will be prompted for a vault password
# Then your default editor opens for you to add secrets:
db_password: "Sup3rS3cure!"
api_key: "ak_live_abc123def456"
ssl_cert_passphrase: "MyC3rtP@ss"

Encrypting Existing Files

If you already have a plaintext file with secrets, encrypt it in place:

# Encrypt an existing file
ansible-vault encrypt vars/database_credentials.yml

# Decrypt for editing
ansible-vault decrypt vars/database_credentials.yml

# Edit without fully decrypting to disk
ansible-vault edit vars/database_credentials.yml

# View encrypted content without modifying
ansible-vault view vars/database_credentials.yml

Using Encrypted Variables in Playbooks

Reference vault-encrypted variables in your Breeze provisioning playbooks just like regular variables:

# playbook.yml
---
- hosts: breeze_servers
  vars_files:
    - group_vars/production/secrets.yml
  tasks:
    - name: Configure database connection
      template:
        src: db-config.j2
        dest: /etc/myapp/database.conf
        mode: '0600'
      vars:
        password: "{{ db_password }}"

    - name: Set API key in environment
      lineinfile:
        path: /etc/environment
        line: "API_KEY={{ api_key }}"
        state: present

Running Playbooks with Vault

Pass the vault password when running your playbook:

# Prompt for password interactively
ansible-playbook -i inventory playbook.yml --ask-vault-pass

# Use a password file (keep it out of version control!)
ansible-playbook -i inventory playbook.yml --vault-password-file ~/.vault_pass

# Set via environment variable
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass
ansible-playbook -i inventory playbook.yml

Encrypting Individual Variables

You can encrypt single values instead of entire files using encrypt_string:

# Encrypt a single string
ansible-vault encrypt_string 'SuperSecret123' --name 'db_password'

# Output (paste this into your vars file):
db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  6566326538643135...

Vault ID and Multiple Passwords

Use vault IDs to manage different passwords for different environments:

# Encrypt with a specific vault ID
ansible-vault encrypt --vault-id prod@prompt secrets_prod.yml
ansible-vault encrypt --vault-id dev@~/.dev_vault_pass secrets_dev.yml

# Run with multiple vault IDs
ansible-playbook playbook.yml \
  --vault-id prod@prompt \
  --vault-id dev@~/.dev_vault_pass

Best Practices

• Never commit vault passwords — add .vault_pass to .gitignore
• Use vault IDs — separate secrets per environment (dev, staging, production)
• Encrypt only what is needed — use encrypt_string for individual values when possible
• Rotate passwords regularly — use ansible-vault rekey to change the vault password
• Restrict file permissions — set chmod 600 on vault password files

Ansible Vault is essential for keeping your Breeze infrastructure secrets safe while still benefiting from version-controlled automation.