Ansible Vault Decrypt — Unlock Encrypted Files and Variables

Introduction

Ansible Vault encrypts sensitive data — passwords, API keys, certificates — within your automation codebase. This guide covers all decryption workflows: viewing encrypted content, editing in-place, decrypting files permanently, and automating vault access in CI/CD pipelines.

Quick Reference

# View encrypted file without changing it
ansible-vault view secrets.yml

# Edit encrypted file (opens in $EDITOR)
ansible-vault edit secrets.yml

# Decrypt file permanently (removes encryption)
ansible-vault decrypt secrets.yml

# Run playbook with vault password prompt
ansible-playbook site.yml --ask-vault-pass

# Run with password file
ansible-playbook site.yml --vault-password-file .vault_pass

View Encrypted Content

# View without modifying
ansible-vault view group_vars/production/vault.yml

# Output to stdout for piping
ansible-vault view secrets.yml | grep db_password

# View with specific vault ID
ansible-vault view --vault-id prod@prompt secrets.yml

Edit Encrypted Files

# Opens decrypted content in $EDITOR, re-encrypts on save
ansible-vault edit group_vars/all/vault.yml

# Use specific editor
EDITOR=nano ansible-vault edit secrets.yml

# Edit with vault ID
ansible-vault edit --vault-id dev@.vault_pass_dev secrets.yml

Decrypt Files Permanently

# Remove encryption (file becomes plaintext)
ansible-vault decrypt secrets.yml
# Decryption successful

# Decrypt with output to different file
ansible-vault decrypt secrets.yml --output secrets-plain.yml

# Decrypt multiple files
ansible-vault decrypt group_vars/*/vault.yml

⚠️ Warning: ansible-vault decrypt permanently removes encryption. The file becomes readable by anyone with file access. Use view or edit instead for temporary access.

Decrypt Inline Variables

# Encrypted variable in vars file
db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  6238396231...

# View the decrypted value
ansible localhost -m debug -a "var=db_password" \
  -e @group_vars/all/vault.yml --vault-password-file .vault_pass

Vault Password Methods

Interactive Prompt

ansible-playbook site.yml --ask-vault-pass
# Vault password: ********

Password File

# Create password file
echo 'MySecretVaultP@ss' > .vault_pass
chmod 600 .vault_pass

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

# Use in ansible.cfg
# [defaults]
# vault_password_file = .vault_pass

ansible-playbook site.yml --vault-password-file .vault_pass

Password Script

#!/bin/bash
# vault_pass.sh — fetch from password manager
# Must output password to stdout
pass show ansible/vault-password

# Or from environment variable
# echo "${ANSIBLE_VAULT_PASSWORD}"

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

Environment Variable

export ANSIBLE_VAULT_PASSWORD_FILE=.vault_pass
# Now all ansible commands use this automatically
ansible-playbook site.yml  # No --vault flags needed

Multiple Vault IDs

# Encrypt with specific vault ID
ansible-vault encrypt --vault-id prod@.vault_pass_prod secrets.yml

# Decrypt with matching ID
ansible-vault decrypt --vault-id prod@.vault_pass_prod secrets.yml

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

CI/CD Integration

GitHub Actions

- name: Run Ansible playbook
  env:
    ANSIBLE_VAULT_PASSWORD: ${{ secrets.VAULT_PASSWORD }}
  run: |
    echo "${ANSIBLE_VAULT_PASSWORD}" > .vault_pass
    chmod 600 .vault_pass
    ansible-playbook -i inventory site.yml --vault-password-file .vault_pass
    rm -f .vault_pass

GitLab CI

deploy:
  script:
    - echo "$VAULT_PASSWORD" > .vault_pass
    - chmod 600 .vault_pass
    - ansible-playbook -i inventory site.yml --vault-password-file .vault_pass
  after_script:
    - rm -f .vault_pass

Jenkins

withCredentials([string(credentialsId: 'ansible-vault-pass', variable: 'VAULT_PASS')]) {
    sh '''
        echo "$VAULT_PASS" > .vault_pass
        chmod 600 .vault_pass
        ansible-playbook -i inventory site.yml --vault-password-file .vault_pass
        rm -f .vault_pass
    '''
}

Troubleshooting

Error	Cause	Fix
`Decryption failed`	Wrong password	Verify password matches encryption
`is not vault encrypted`	File is plaintext	No decryption needed
`Vault password client script had nonzero exit`	Script error	Check script permissions and output
`ERROR! vault-id not found`	Mismatched vault ID	Use matching `--vault-id`
`input is not vault encrypted data`	Corrupted file	Check for manual edits to encrypted content

Best Practices

Never commit .vault_pass to Git — always in .gitignore
Use view/edit over decrypt — avoid leaving plaintext on disk
Use vault IDs for multi-environment setups (dev/staging/prod)
Rotate vault passwords periodically — re-encrypt with ansible-vault rekey
Prefer encrypt_string for single values — encrypt only what's sensitive
Store vault password in a secrets manager (HashiCorp Vault, AWS Secrets Manager)

Conclusion

Use ansible-vault view to inspect, edit to modify, and decrypt only when you need permanent plaintext access. Automate vault password delivery via password files or scripts in CI/CD. Never store the vault password in Git — use environment variables, CI secrets, or external password managers.