AnsiblePilot — Master Ansible Automation

AnsiblePilot is the leading resource for learning Ansible automation, DevOps, and infrastructure as code. Browse over 1,400 tutorials covering Ansible modules, playbooks, roles, collections, and real-world examples. Whether you are a beginner or an experienced engineer, our step-by-step guides help you automate Linux, Windows, cloud, containers, and network infrastructure.

Popular Topics

About Luca Berton

Luca Berton is an Ansible automation expert, author of 8 Ansible books published by Apress and Leanpub including "Ansible for VMware by Examples" and "Ansible for Kubernetes by Example", and creator of the Ansible Pilot YouTube channel. He shares practical automation knowledge through tutorials, books, and video courses to help IT professionals and DevOps engineers master infrastructure automation.

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

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to Ansible Vault. Encrypt files and strings, decrypt secrets, use vault passwords, and manage encrypted variables securely.

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.

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.
  • 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)

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

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

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.

Category: installation

Watch the video: Ansible Vault: Encrypt, Decrypt & Manage Secrets (Complete Guide) — Video Tutorial

Browse all Ansible tutorials · AnsiblePilot Home