Ansible Vault: keep passwords and keys encrypted in your repo

Playbooks often need secrets: database passwords, API tokens, TLS keys. Writing them in plain YAML and committing them to Git leaks them to everyone with read access. Ansible Vault encrypts that data with a password (AES256), and Ansible decrypts it in memory when the playbook runs.

You can encrypt a whole file, typically a variables file, or a single value inside an otherwise readable file.

Encrypt whole files

ansible-vault create group_vars/db/vault.yml      # new encrypted file, opens your editor
ansible-vault encrypt group_vars/db/vault.yml     # encrypt an existing plain file
ansible-vault view group_vars/db/vault.yml        # read without editing
ansible-vault edit group_vars/db/vault.yml        # decrypt to a temp file, edit, re-encrypt
ansible-vault rekey group_vars/db/vault.yml       # change the password

An encrypted file starts with a header such as $ANSIBLE_VAULT;1.1;AES256 followed by hex-encoded ciphertext. Ansible loads it like any other group_vars file as long as it can decrypt it.

Warning: ansible-vault decrypt FILE writes the plain text back to disk permanently. Prefer view or edit, and run git status before committing if you ever decrypt a file.

A layout that stays readable

A common convention is to keep two files per group: a plain one that names every variable, and a vaulted one that holds the secret values with a vault_ prefix. Then grep still finds where a variable is defined, even though the value is encrypted.

# group_vars/db/vars.yml (plain text)
db_user: appuser
db_password: "{{ vault_db_password }}"

# group_vars/db/vault.yml (encrypted with ansible-vault)
vault_db_password: CHANGE_ME

Encrypt a single value

encrypt_string prints a YAML snippet you can paste into any vars file:

ansible-vault encrypt_string --vault-id dev@prompt 'CHANGE_ME' --name 'db_password'
ansible-vault encrypt_string --vault-id dev@prompt --prompt --name 'db_password'

db_password: !vault |
          $ANSIBLE_VAULT;1.2;AES256;dev
          6231...(hex lines)...

The !vault tag tells Ansible to decrypt the value. Because the secret is typed on the command line here, it may end up in your shell history; add -p (--prompt) instead of the string and encrypt_string asks for it with hidden input.

Run playbooks with vaulted data

ansible-playbook site.yml --ask-vault-pass
ansible-playbook site.yml --vault-password-file ~/.vault_pass
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass

A password file contains the password on one line. Keep it outside the repository and readable only by you (chmod 600 ~/.vault_pass). The password file can also be an executable script that prints the password, which is how you fetch it from a password manager or a secrets service in CI.

Vault IDs: several passwords

Use vault IDs when different environments need different passwords. The format is label@source, where the source is a password file or prompt. The label is stored in the encrypted header (format 1.2), so Ansible knows which password to try first.

ansible-vault create --vault-id prod@prompt group_vars/prod/vault.yml
ansible-playbook site.yml --vault-id dev@~/.vault_pass_dev --vault-id prod@prompt
ansible-vault rekey --new-vault-id prod@prompt group_vars/prod/vault.yml

Common errors

• Attempting to decrypt but no vault secrets found: the playbook loaded vaulted content but you gave no password. Add --ask-vault-pass, --vault-id or a password file.
• Decryption failed (no vault secrets were found that could decrypt): a password was given but it is the wrong one for that file or value.

Do not leak the decrypted value

Vault protects data at rest. At run time the value is plain text, and a task that uses it can print it in its output, for example on failure or with -v. Add no_log: true to tasks that handle secrets so their arguments and results are hidden from the output and logs. It does not hide debugging output, so avoid verbose debugging runs in production.

Official documentation

• Encrypting content with Ansible Vault
• Using encrypted variables and files
• Logging Ansible output (no_log)