Ansible Vault: Encrypt | Decrypt a String

Ansible files may often contain different secret strings e.g. passwords, tokens, keys etc., and the good practice is not to store them in a plain text but to encrypt them.

This is especially important if your Ansible files are tracked in a source control system.

This note shows the examples of how to encrypt and decrypt a string using Ansible vault.

Cool Tip: Encrypt files and messages with a password from the Linux command line, using OpenSSL! Read More →

Encrypt a String using Ansible Vault

Use the following syntax to encrypt a string using Ansible vault:

$ ansible-vault encrypt_string '<secret_string>' --name '<variable_name>'

For example, to create a variable user_password with the encrypted string P@$$w0rd, run:

$ ansible-vault encrypt_string 'P@$$w0rd' --name 'user_password'
- sample output -
New Vault password: 
Confirm New Vault password: 
user_password: !vault |
            $ANSIBLE_VAULT;1.1;AES256
            6562383862653033303064643838366139363338616266393135323431626265653334
            3839356135353062643637353866643937363366383039640a39396565326662356432
            6434666633663331323836653538396164613137326665666532633037353961656663
            3837
Encryption successful

Now you can save this variable with the encrypted string in an inventory, playbook, role, etc. or set it directly in a task, for example:

# roles/ansible_vault_example/tasks/main.yml
---
- name: "Set variables"
  set_fact:
    user_name: "admin"
    user_password: !vault |
                $ANSIBLE_VAULT;1.1;AES256
                6562383862653033303064643838366139363338616266393135323431626265653334
                3839356135353062643637353866643937363366383039640a39396565326662356432
                6434666633663331323836653538396164613137326665666532633037353961656663
                3837

- debug:
    msg: "The user '{{ user_name }}' has a password '{{ user_password }}'"

Decrypt a String using Ansible Vault

If you run a playbook with the encrypted string without specifying a vault password to decrypt it, you will get an Ansible error as follows:

TASK [ansible_vault_example : Set variables] ****************************************
fatal: [127.0.0.1]: FAILED! => 
  msg: Attempting to decrypt but no vault secrets found

Decrypt using ansible-playbook command

To be prompted for a vault password, execute the ansible-playbook command with a --ask-vault-pass option:

$ ansible-playbook playbook.yml -i inventory.ini --ask-vault-pass

To load the vault password from a file (useful in different automation scenarios), create the vault.txt file with the password that you used to encrypt the string, e.g:

$ echo "vaultPassw0rd" > vault.txt

Ensure permissions on the vault.txt are such that no one else can access it and do not add this file to a source control:

$ chmod 600 vault.txt
$ echo "vault.txt" >> .gitignore

Run your playbook with the --vault-password-file option to decrypt the string without being prompted for the password:

$ ansible-playbook playbook.yml -i inventory.ini --vault-password-file=vault.txt

Decrypt using ansible-vault command

To decrypt the string without running a playbook:

$ ansible-vault decrypt
- sample output -
Vault password: 
Reading ciphertext input from stdin
$ANSIBLE_VAULT;1.1;AES256
6562383862653033303064643838366139363338616266393135323431626265653334
3839356135353062643637353866643937363366383039640a39396565326662356432
6434666633663331323836653538396164613137326665666532633037353961656663
3837 Enter, Ctrl + D
Decryption successful
P@$$w0rd

Note that there should be no spaces in the vault secret string, otherwise you will get:

ERROR! Vault format unhexlify error: Non-hexadecimal digit found for -

To decrypt the string without running a playbook non-interactively:

$ echo '$ANSIBLE_VAULT;1.1;AES256
6562383862653033303064643838366139363338616266393135323431626265653334
3839356135353062643637353866643937363366383039640a39396565326662356432
6434666633663331323836653538396164613137326665666532633037353961656663
3837' | ansible-vault decrypt --vault-password-file=vault.txt

Cool Tip: How to fix the Ansible’s “sudo: a password is required” error! Read more →