Ansible Vault: Encrypt, Decrypt & Manage Secrets (Complete Guide)

How to decrypt an Ansible Vault?

From an encrypted file to plaintext using the correct password. I will show you a live Playbook with some simple Ansible code. I'm Luca Berton, and welcome to today's episode of Ansible Pilot.

See also: Use Ansible Vault in Ansbile Playbook - ansible vault

ansible-vault

• Included in Ansible installation • Ansible Vault • command line

The ansible-vault command is included in every Ansible installation for the most modern operating system. It is a command line tool so interact with that using your terminal. Using the ansible-vault command, you could perform any Ansible vault operation: encryption, decryption, change of password, etc.

Links

• https://docs.ansible.com/ansible/latest/user_guide/vault.html

See also: Ansible selectattr & map Filters: Filter Data from Lists (Complete Guide)

Playbook

I will show you how to decrypt an Ansible Vault using the ansible-vault command line utility. At the beginning of this example, we start with an encrypted Ansible vault, and once we enter the correct password, we obtain a cleartext file.

execution

$ ansible-vault decrypt encrypted-to-plain.yml 
Vault password: 
Decryption successful

before execution

$ cat encrypted-to-plain.yml 
$ANSIBLE_VAULT;1.1;AES256
65333637643363376438633838346563353666636433613032333663666137613839333564393238
3930333031633134346461303636623937353561643464390a363534383938396336346130653231
34356437363733313638336437343735366362343031663866326135633538373237646537356638
6163373837343332660a323666666534353561656464353033613137333463316534663062643561
34373865636163626163313235393239653539356665373361373939633138373137643264386533
3761646565643732396531313561366364353031373731353839

after execution

$ cat encrypted-to-plain.yml 
---
password: mysupersecretpassword

Conclusion

Now you know how to decrypt an Ansible Vault.

Ansible Vault Overview

Ansible Vault provides encryption for sensitive data like passwords, API keys, and certificates. It uses AES-256 encryption, which is the same standard used by banks and governments.

When to Use Vault

• Storing database passwords in group_vars/ • Encrypting SSH private keys • Protecting API tokens and secrets • Securing cloud credentials (AWS, Azure, GCP)

See also: Ansible terminology - What is an Ansible Playbook?

Decrypt Methods

Method 1: Decrypt entire file

# Interactive password prompt
ansible-vault decrypt secrets.yml
# Using a password file
ansible-vault decrypt secrets.yml --vault-password-file=.vault_pass
# Using vault ID (Ansible 2.4+)
ansible-vault decrypt secrets.yml --vault-id prod@.vault_pass

Method 2: View without decrypting

# View contents without modifying the file
ansible-vault view secrets.yml
# Pipe to other commands
ansible-vault view secrets.yml | grep database_password

Method 3: Decrypt inline during playbook run

# Ansible automatically decrypts vault files during execution
ansible-playbook playbook.yml --ask-vault-pass
# Using password file (for CI/CD)
ansible-playbook playbook.yml --vault-password-file=.vault_pass

Method 4: Decrypt single variables

If you encrypted a single variable with ansible-vault encrypt_string:

# In your vars file
database_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  65333637643363376438...

These are automatically decrypted when the playbook runs. To view the value:

# Use debug module
ansible localhost -m debug -a "var=database_password" -e @vars.yml --ask-vault-pass

Using Password Files

For automation (CI/CD, cron jobs), use a password file instead of interactive prompts:

# Create a password file
echo 'MyVaultPassword' > .vault_pass
chmod 600 .vault_pass
# Add to .gitignore (CRITICAL!)
echo '.vault_pass' >> .gitignore
# Use it
ansible-vault decrypt secrets.yml --vault-password-file=.vault_pass

Configure default password file in ansible.cfg

[defaults]
vault_password_file = .vault_pass

Troubleshooting Decryption Failures

Error: "Decryption failed"

ERROR! Decryption failed on secrets.yml

Cause: Wrong password. Double-check your vault password.

Error: "Attempting to decrypt but no vault secrets found"

ERROR! Attempting to decrypt but no vault secrets found

Cause: You didn't provide --ask-vault-pass or --vault-password-file.

Error: "input is not vault encrypted data"

ERROR! input is not vault encrypted data

Cause: The file isn't actually vault-encrypted. Check if it starts with $ANSIBLE_VAULT;1.1;AES256.

Multiple Vault IDs

For managing different secrets with different passwords (e.g., dev vs prod):

# Encrypt with vault ID
ansible-vault encrypt secrets.yml --vault-id prod@prompt
# Decrypt with vault ID
ansible-vault decrypt secrets.yml --vault-id prod@.vault_pass_prod
# Run playbook with multiple vault IDs
ansible-playbook playbook.yml \
  --vault-id dev@.vault_pass_dev \
  --vault-id prod@.vault_pass_prod

FAQ

Can I change the vault password without decrypting?

Yes! Use ansible-vault rekey:

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

How do I encrypt only specific variables, not entire files?

Use encrypt_string:

ansible-vault encrypt_string 'my_secret_value' --name 'my_variable' --ask-vault-pass

Is Ansible Vault secure enough for production?

Yes. AES-256 is military-grade encryption. The weak point is password management — use strong, unique passwords and store them securely (e.g., in a secrets manager like HashiCorp Vault for the vault password itself).

Decrypt a File

# Decrypt (removes encryption)
ansible-vault decrypt secrets.yml
# Decrypt with password file
ansible-vault decrypt secrets.yml --vault-password-file ~/.vault_pass

View Without Decrypting

# View encrypted file contents
ansible-vault view secrets.yml
# With password file
ansible-vault view secrets.yml --vault-password-file ~/.vault_pass

Edit Encrypted File

# Opens in editor, re-encrypts on save
ansible-vault edit secrets.yml
# With specific editor
EDITOR=nano ansible-vault edit secrets.yml

Encrypt a File

# Encrypt existing file
ansible-vault encrypt secrets.yml
# Create new encrypted file
ansible-vault create secrets.yml
# Encrypt with specific vault ID
ansible-vault encrypt --vault-id prod@prompt secrets.yml

Encrypt String (Inline)

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

Output:

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

Use in Playbooks

# Prompt for password
ansible-playbook site.yml --ask-vault-pass
# Password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass
# Environment variable
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass
ansible-playbook site.yml

Password File

# Create password file
echo 'my-vault-password' > ~/.vault_pass
chmod 600 ~/.vault_pass
# Reference in ansible.cfg
# [defaults]
# vault_password_file = ~/.vault_pass

Change Vault Password (Rekey)

ansible-vault rekey secrets.yml
# Prompts for old password, then new password
# With files
ansible-vault rekey secrets.yml \
  --vault-password-file old_pass \
  --new-vault-password-file new_pass

Multiple Vault IDs

# Encrypt with named vault
ansible-vault encrypt --vault-id prod@~/.vault_prod secrets.yml
# Use multiple vaults
ansible-playbook site.yml \
  --vault-id dev@~/.vault_dev \
  --vault-id prod@~/.vault_prod

Vault in CI/CD

# GitHub Actions
- name: Run Ansible
  run: ansible-playbook site.yml --vault-password-file vault_pass
  env:
    ANSIBLE_VAULT_PASSWORD: ${{ secrets.VAULT_PASSWORD }}
# Create password file from secret
- run: echo "${{ secrets.VAULT_PASSWORD }}" > vault_pass && chmod 600 vault_pass

Common Patterns

# Encrypted variables file
# group_vars/production/vault.yml (encrypted)
vault_db_password: SuperSecret123
vault_api_key: abc123xyz
# group_vars/production/vars.yml (plain, references vault)
db_password: "{{ vault_db_password }}"
api_key: "{{ vault_api_key }}"

FAQ

"Decryption failed" error?

Wrong password. There's no way to recover if you've lost the vault password.

Can I have both encrypted and plain vars in one file?

No — a file is either fully encrypted or fully plain. Use inline !vault for mixed files, or split into vault.yml and vars.yml.

How do I check if a file is encrypted?

head -1 secrets.yml
# $ANSIBLE_VAULT;1.1;AES256 = encrypted

Is Ansible Vault secure?

Yes — uses AES-256 encryption. The security depends on your password strength and how you manage the password file.

Encrypt a File

ansible-vault encrypt secrets.yml
# Prompts for password, encrypts in-place

Decrypt a File

# Decrypt in-place
ansible-vault decrypt secrets.yml
# View without decrypting
ansible-vault view secrets.yml
# Edit encrypted file
ansible-vault edit secrets.yml

Encrypt a String

ansible-vault encrypt_string 'SuperSecret123' --name 'db_password'
# Output:
# db_password: !vault |
#   $ANSIBLE_VAULT;1.1;AES256
#   616364...

Use in Playbook

# vars/vault.yml (encrypted)
db_password: SuperSecret123
api_key: abc123def456
# playbook.yml
- hosts: all
  vars_files:
    - vars/vault.yml
  tasks:
    - template:
        src: config.j2
        dest: /etc/myapp/config
      no_log: true

Run with Vault Password

# Prompt for password
ansible-playbook site.yml --ask-vault-pass
# Password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass
# Password from script
ansible-playbook site.yml --vault-password-file ./get-vault-pass.sh
# Environment variable
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass
ansible-playbook site.yml

Re-key (Change Password)

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

Multiple Vault IDs

# Encrypt with specific ID
ansible-vault encrypt --vault-id prod@prompt secrets-prod.yml
ansible-vault encrypt --vault-id dev@~/.dev_pass secrets-dev.yml
# Use both
ansible-playbook site.yml \
  --vault-id dev@~/.dev_pass \
  --vault-id prod@prompt

Inline Encrypted Variables

# In group_vars/production.yml (unencrypted file)
db_host: db.example.com
db_port: 5432
db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  616364313932356131...
# Only the password is encrypted, rest is readable

Best Practices

# 1. Prefix vault variables
vault_db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  ...
# 2. Reference in plain vars file
db_password: "{{ vault_db_password }}"
# 3. Use no_log for tasks with secrets
- template:
    src: config.j2
    dest: /etc/myapp/config
  no_log: true
# 4. Never commit vault passwords to git
# .gitignore:
# .vault_pass
# *.vault_pass

Vault Password File

# Create password file
echo 'MyVaultPassword' > ~/.vault_pass
chmod 600 ~/.vault_pass
# ansible.cfg
# [defaults]
# vault_password_file = ~/.vault_pass

FAQ

Can I encrypt an entire playbook?

Yes, but don't — you can't read or edit it easily. Encrypt only the vars files containing secrets.

How secure is Ansible Vault?

AES-256 encryption. Secure as long as the password is strong and not committed to version control.

Can I use Vault with AWX/AAP?

Yes — AWX has a credential type for vault passwords. Store the vault password as an AWX credential.

Related Articles

• the Ansible Vault walkthrough