Ansible Vault: Encrypt Secrets in Playbooks and Variables

What is Ansible Vault?

Ansible Vault encrypts sensitive data — passwords, API keys, certificates, SSH keys — so you can safely store them in version control alongside your playbooks.

Create an Encrypted File

# Interactive — prompts for vault password
ansible-vault create secrets.yml

# With password file
ansible-vault create --vault-password-file .vault_pass secrets.yml

Inside the editor:

db_password: "s3cretP@ssw0rd"
api_key: "sk-abc123def456"
ssl_private_key: |
  -----BEGIN PRIVATE KEY-----
  MIIEvQIBADANBgkqhki...
  -----END PRIVATE KEY-----

Encrypt an Existing File

ansible-vault encrypt group_vars/production/secrets.yml

Decrypt a File

# Permanently decrypt
ansible-vault decrypt secrets.yml

# View without decrypting
ansible-vault view secrets.yml

Edit an Encrypted File

ansible-vault edit secrets.yml

Encrypt a Single String

ansible-vault encrypt_string 'mySecretPassword' --name 'db_password'

Output:

db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  62313365396662343061393464336163383764316462...

Paste this directly into your playbook or vars file.

Using Vault in Playbooks

Encrypted Variables File

# group_vars/production/secrets.yml (encrypted)
db_password: "s3cretP@ssw0rd"
api_token: "tok_abc123"

# playbook.yml
- name: Deploy application
  hosts: webservers
  vars_files:
    - group_vars/production/secrets.yml
  tasks:
    - name: Configure database
      ansible.builtin.template:
        src: db.conf.j2
        dest: /opt/app/db.conf
      no_log: true

Inline Encrypted Variables

vars:
  db_password: !vault |
    $ANSIBLE_VAULT;1.1;AES256
    62313365396662343061393464336163383764316462...
  app_secret: !vault |
    $ANSIBLE_VAULT;1.1;AES256
    33363535313439646234663362613839...

Running Playbooks with Vault

# Prompt for password
ansible-playbook deploy.yml --ask-vault-pass

# Use a password file
ansible-playbook deploy.yml --vault-password-file .vault_pass

# Use environment variable
export ANSIBLE_VAULT_PASSWORD_FILE=.vault_pass
ansible-playbook deploy.yml

Password File

# Create a password file
echo 'my-vault-password' > .vault_pass
chmod 600 .vault_pass

# Add to .gitignore!
echo '.vault_pass' >> .gitignore

Password from Script

# vault_pass.sh
#!/bin/bash
# Pull password from your password manager or secret store
pass show ansible/vault-password

chmod +x vault_pass.sh
ansible-playbook deploy.yml --vault-password-file vault_pass.sh

Multiple Vault IDs

Use different passwords for different environments:

# Encrypt with vault ID
ansible-vault encrypt --vault-id prod@prompt secrets-prod.yml
ansible-vault encrypt --vault-id dev@.vault_pass_dev secrets-dev.yml

# Run with multiple vault IDs
ansible-playbook deploy.yml \
  --vault-id dev@.vault_pass_dev \
  --vault-id prod@prompt

Change Vault Password

ansible-vault rekey secrets.yml
# Prompts for old password, then new password

ansible-vault rekey --new-vault-password-file new_pass secrets.yml

Common Error: "no vault secrets found"

ERROR! Attempting to decrypt but no vault secrets found

Fix: Provide the vault password:

# Add --ask-vault-pass
ansible-playbook deploy.yml --ask-vault-pass

# Or set the password file
export ANSIBLE_VAULT_PASSWORD_FILE=.vault_pass

Best Practices

Never commit .vault_pass — add to .gitignore
Use no_log: true on tasks using vault variables
Separate secrets from code — put encrypted vars in group_vars/*/vault.yml
Use vault IDs for multi-environment setups
Rotate vault passwords periodically with ansible-vault rekey
Use encrypt_string for individual values instead of encrypting entire files

Project Structure

project/
├── .gitignore          # Contains .vault_pass
├── .vault_pass         # NOT in git
├── ansible.cfg
├── group_vars/
│   ├── all/
│   │   └── vars.yml    # Non-secret variables
│   ├── production/
│   │   ├── vars.yml    # Non-secret production vars
│   │   └── vault.yml   # Encrypted secrets
│   └── staging/
│       ├── vars.yml
│       └── vault.yml   # Encrypted secrets
├── playbooks/
└── inventory/

# ansible.cfg
[defaults]
vault_password_file = .vault_pass

Command Reference

Command	Description
`ansible-vault create FILE`	Create encrypted file
`ansible-vault edit FILE`	Edit encrypted file
`ansible-vault view FILE`	View encrypted file
`ansible-vault encrypt FILE`	Encrypt existing file
`ansible-vault decrypt FILE`	Decrypt file
`ansible-vault rekey FILE`	Change password
`ansible-vault encrypt_string`	Encrypt a string

Learn more about secure automation in our 800+ tutorials on AnsibleByExample.