Every Ansible user hits the same wall sooner or later: your playbook needs a database password, an API token, or a TLS private key, and the only obvious place to put it is a variable in plain text — one git commit away from living forever in your repository history. Ansible Vault is Ansible’s built-in answer to that problem. It encrypts secrets with AES-256 so your repository stores only ciphertext, while playbooks decrypt the values transparently at runtime when you supply the vault password.

In this guide you will learn the complete ansible vault workflow: creating and editing encrypted files, encrypting individual values with encrypt_string, managing vault passwords with files and scripts, using vault IDs for multiple environments, rotating passwords with rekey, and running vaulted playbooks safely in CI/CD pipelines.
Prerequisites
- Ansible 2.9 or newer on your control node (check with
ansible --version) - A working inventory and at least one playbook — if you are new to Ansible, start with our Ansible beginner’s guide to inventory, playbooks, and roles
- A terminal where you can run
ansible-vaultcommands
Why Plaintext Secrets Do Not Belong in Git
Storing a password in group_vars/all.yml feels harmless until you consider how git remembers things: every commit is permanent, every clone carries the full history, and deleting the secret in a later commit changes nothing — it is still sitting in the earlier commits, in every fork, and possibly in a CI log somewhere. Credential scanners routinely find live API keys in public repositories within minutes of them being pushed.
.gitignore does not fix this either: the moment a secrets file is tracked, ignoring it later has no effect on history. Ansible Vault changes the equation instead. The encrypted file is safe to commit because without the vault password it is just opaque ciphertext — and the password itself never enters the repository.
Creating and Editing Encrypted Files with Ansible Vault
The core ansible vault commands operate on whole files. Each one prompts for the vault password unless you tell it otherwise (we cover non-interactive options below):
# Create a new encrypted file (opens your editor; encrypts on save)
ansible-vault create group_vars/webservers/vault.yml
# View an encrypted file without editing it
ansible-vault view group_vars/webservers/vault.yml
# Edit an encrypted file in place
ansible-vault edit group_vars/webservers/vault.yml
# Encrypt an existing plaintext file
ansible-vault encrypt group_vars/webservers/secrets.yml
# Decrypt a file back to plaintext
ansible-vault decrypt group_vars/webservers/secrets.yml
# Decrypt to a different file, leaving the original untouched
ansible-vault decrypt --output /tmp/secrets-plain.yml group_vars/webservers/secrets.yml
A typical vaulted file looks like this in your editor:
db_password: "correct-horse-battery-staple"
api_token: "tok_live_9f8a2b1c"
backup_encryption_key: "b3JkZXItc2VjcmV0LWtleQ=="
And like this in git — a header identifying the vault format, followed by ciphertext:
$ANSIBLE_VAULT;1.1;AES256
38663639383532373231613735353738636134313663346465663833386230663662373265383939
...
You can safely commit files that start with $ANSIBLE_VAULT; the values inside are encrypted with AES-256 and reveal nothing without the password.
Using Ansible Vault encrypt_string for Inline Values
Sometimes encrypting a whole file is overkill — you have one password in a variables file that is otherwise harmless to read. encrypt_string encrypts a single value that you paste inline:
ansible-vault encrypt_string 'correct-horse-battery-staple' --name 'db_password'
The output is a ready-to-paste YAML block:
db_password: !vault |
$ANSIBLE_VAULT;1.1;AES256
38663639383532373231613735353738636134313663346465663833386230663662373265383939
...
Two flags are worth knowing: -p (or --prompt) lets you type the secret interactively instead of passing it on the command line, keeping it out of your shell history; --stdin-name reads the value from stdin, which is handy in scripts. One caution: opening a file with ansible-vault edit re-encrypts it on save, rewriting the ciphertext and creating a noisy git diff even when nothing changed. For single values, encrypt_string avoids that churn entirely.
Referencing Vaulted Variables in Playbooks
Encrypted files slot into playbooks like any other variables. The most common pattern is a vars_files entry:
- name: Configure the web servers
hosts: webservers
vars_files:
- group_vars/webservers/vault.yml
tasks:
- name: Create the application database user
community.mysql.mysql_user:
name: app_user
password: "{{ db_password }}"
priv: "appdb.*:ALL"
state: present
You can also load vaulted files with include_vars, drop them into group_vars/ or host_vars/ (any .yml there loads automatically), or pass one on the command line with -e @vault.yml. At runtime, supply the password and Ansible decrypts transparently:
# Prompt for the vault password interactively
ansible-playbook -J -i inventory.ini site.yml
# Read the password from a file instead
ansible-playbook --vault-password-file ~/.vault_pass -i inventory.ini site.yml
Managing Ansible Vault Passwords for CI/CD
Interactive prompts do not work in automation, so pipelines need the vault password from a file or a script. Create a password file with strict permissions and keep it out of version control:
# One line: the vault password and nothing else
printf '%s' 'correct-horse-battery-staple' > ~/.vault_pass
chmod 600 ~/.vault_pass
# Never commit it
echo ".vault_pass" >> .gitignore
To avoid passing the flag on every run, set it once in ansible.cfg:
[defaults]
vault_password_file = ~/.vault_pass
The password file can also be an executable script: if the file is executable, Ansible runs it and uses its stdout as the password. That lets you fetch the secret from a password manager or cloud secrets service at runtime instead of storing it on disk. In GitHub Actions or GitLab CI, the usual pattern is writing a CI secret to a temporary file with 600 permissions at the start of the job, then deleting it when the job finishes.
Ansible Vault IDs for Multiple Environments
One password for everything is convenient until development and production need different secrets. Vault IDs let you label passwords so several can coexist. The format is label@source, where the source is a prompt, a file, or a script:
# Encrypt the staging secrets with the "staging" identity (prompts for it)
ansible-vault create --vault-id staging@prompt group_vars/staging/vault.yml
# Encrypt the production secrets with a different password file
ansible-vault create --vault-id prod@~/.vault_prod group_vars/prod/vault.yml
# Run a playbook that uses both
ansible-playbook --vault-id staging@prompt --vault-id prod@~/.vault_prod -i inventory.ini site.yml
When more than one vault ID is in play, tell Ansible which identity should do the encrypting:
ansible-vault encrypt_string --vault-id prod@~/.vault_prod \
--encrypt-vault-id prod 's3cr3t-prod-token' --name 'api_token'
Encrypted strings carry their vault ID, so ansible-playbook knows which password to try for each value. You can also declare the list permanently in ansible.cfg with vault_identity_list.
Rotating Passwords with Ansible Vault rekey
When a team member leaves or a password is suspected of leaking, rekey re-encrypts files with a new password:
# Interactive: prompts for the current password, then the new one twice
ansible-vault rekey group_vars/webservers/vault.yml
# Non-interactive: current password from one file, new password from another
ansible-vault rekey --vault-password-file ~/.vault_pass \
--new-vault-password-file ~/.vault_pass_new group_vars/webservers/vault.yml
With vault IDs, use --new-vault-id to select the identity holding the new password. Remember that rekeying only changes the files you point it at — audit every vaulted file encrypted with the old password, then update password files, CI secrets, and team documentation to match.
Troubleshooting Ansible Vault
- “Decryption failed (no vault secrets were found that could decrypt)” — wrong password, or the file was encrypted with a different vault ID than the one you supplied. Check which identity encrypted the file and pass the matching
--vault-id. - “input is not vault encrypted data” — you ran
decrypt,view, orediton a plaintext file. Runansible-vault encrypton it first. - YAML parse errors after pasting an
encrypt_stringblock — almost always indentation. The!vault |block must be indented consistently under its key, and the trailing pipe must be preserved. - Playbook reports a variable as undefined — the vaulted file was never loaded. Check the
vars_filespath, thegroup_vars/directory naming, and that the inventory group matches. - Password file ignored or permission errors — the file should be readable only by you (
chmod 600); also confirmansible.cfgpoints at the right path. - A lost vault password means lost data. There is no recovery mechanism — if nobody knows the password, the encrypted values are gone for good. Store passwords in a team password manager, not in chat logs.
Ansible Vault Best Practices
- One password per environment. Never reuse the production vault password for development or CI experiments.
- Never commit password files. Add them to
.gitignore, document how teammates obtain them, and prefer executable password scripts backed by a secrets manager where possible. - Review vaulted changes like any other code. AI-assisted code review for Terraform and Ansible is a good second pair of eyes for catching an accidentally committed plaintext secret before merge.
- Keep vaulted files small and focused — one per role or environment — to reduce merge conflicts and make rekeying less painful.
- Encrypt the minimum. Use
encrypt_stringfor one-off values so diffs stay readable and files stay reviewable. - Rotate on personnel changes with
rekey, and keep an inventory of which files use which vault ID.
Conclusion
Ansible Vault turns secret management from a git-history liability into a routine part of your workflow: files encrypt with a single command, individual values encrypt inline with encrypt_string, vault IDs keep environments separated, and password files or scripts make the whole thing work unattended in CI/CD. Adopt it before your next git push — your future self will thank you. For the complete reference, see the official Ansible Vault documentation.