In this comprehensive Ansible tutorial, we will explain what Ansible Vault is, how it works, and walk you through how to use Ansible Vault to protect sensitive data such as passwords or private keys.
If you don’t have Ansible installed, you can follow our tutorial on how to install and configure Ansible on Ubuntu 20.04, and continue with the below steps once the server is configured.
What is Ansible Vault?
Ansible Vault is an Ansible feature that lets you encrypt confidential and sensitive information. Ansible Vault can encrypt text files, variables, and entire YAML playbooks. It uses AES 256 algorithm to provide symmetric encryption. This essentially means that it uses the same password for encrypting and decrypting files.
How does Ansible Vault work?
Ansible Vault allows users to encrypt sensitive data such as passwords, API keys, and other confidential information by using symmetric encryption to encrypt files and their contents, which can be decrypted using a password or key.
A typical Ansible Playbook usually contains a bucketload of confidential information such as users' passwords, SSH private keys, tokens, and SSL certificates to mention a few. Saving such sensitive information in plain text is considered a bad practice and poses a security threat to the infrastructure managed by Ansible. Hackers can retrieve such confidential information and wreak havoc on your infrastructure. Taking this into consideration, it's always recommended to safeguard such sensitive data.
To be more specific, Ansible vault performs the following tasks:
- creates an encrypted file
- Encrypts and decrypts files
- Views encrypted files without compromising the encryption
- Edits encrypted files
- Resets encrypted keys
Now that you have a glimpse of what Ansible vault is, what it does, and how it works, let us now see it in action and how you can use Ansible Vault in your workflows to manage sensitive data.
How to use Ansible Vault?
Managing encrypted content in Ansible is made possible using the
ansible-vault command. The command not only encrypts but also views, modifies, and decrypts files.
Here are various ways you can use Ansible Vault to manage sensitive files:
How To Create a New Encrypted File Using Ansible Vault
To create a new encrypted file with Ansible vault, invoke the
ansible-vault create command followed by the name of a file to be encrypted.
For example, to create a new encrypted file called
secrets.yml that stores variables with passwords, run the following command.
ansible-vault create secrets.yml
Once you run the command, you will be prompted for a vault password. Provide it and confirm it.
Next, Ansible will open a command-line text editor. In this case, the editor is vim.
Once you are done typing your content, save the changes. As soon as the changes to the file have been saved, Ansible applies the encryption immediately.
To confirm that encryption has been applied, try viewing the file using the
cat command. Instead of viewing the content that you saved, you will see an encrypted block.
How To View an Encrypted File
To view the contents of an encrypted file, use the ansible-vault view command followed by the file name. The command prints out the contents of the file on the terminal.
ansible-vault view secrets.yml
Once you execute the command, you will be prompted for the password that you initially used to encrypt the file. Once you provide the password, the contents of the file will be displayed.
How To Edit Encrypted files
Sometimes, you might need to access and edit encrypted files. To accomplish this, use the
ansible-vault edit command.
ansible-vault edit secrets.yml
Again, you will be prompted for the file’s password. Once provided, Ansible will open the file in a text editor. From there you can edit your file as you deem fit and save the changes.
How To Encrypt an Existing File
If you already have an existing file that you want to encrypt, you can do so using the
ansible-vault encrypt command. To demonstrate this, we are going to create a sample file and add some content to it as follows.
echo ‘Ansible Encryption In Action’ > sample.txt
Next, we will encrypt it as shown.
ansible-vault encrypt sample.yml
Once again, you will be prompted for the file’s password. Type in the password and confirm it. You will then receive a notification that the encryption was successful.
If you check the file using the cat command, you will observe a similar encrypted block as we saw earlier.
How To Change The Password Of Encrypted Files
In case you need to change the password of an encrypted file, invoke the
ansible-vault rekey command as follows.
ansible-vault rekey sample.txt
Once you run the command, you will be required to provide the file’s current password. Thereafter, you will be prompted to provide a new vault password and then confirm it.
How to Decrypt Encrypted Files
To remove encryption from a vault-encrypted file, use the
ansible-vault decrypt command as follows.
ansible-vault decrypt sample.txt
You will be prompted for the file’s decryption password upon which the file will be decrypted.
Once a file is decrypted, all your sensitive information is essentially open to the rest of the world. As a precaution, it’s recommended that you encrypt the file again or transfer your data to another encrypted file and delete the decrypted file.
How To Decrypt Encrypted Files During Playbook Runtime
There are various ways of decrypting a file during playbook runtime. The easiest approach is to prompt for the file’s password using the
To demonstrate this, we have a custom inventory file at
~/ansible/inventory which is already encrypted.
During playbook runtime, we will pass the
--ask-vault-pass parameter to prompt for the inventory’s encryption password upon which the playbook will be executed.
sudo ansible-playbook -i ansible/inventory sample-playbook.yaml –ask-vault-pass
This method of file decryption at runtime only works if all the encrypted files referenced by the playbook are encrypted using the same password.
Using Ansible Vault Password File
Manually entering a password during playbook runtime is not only tedious but also undermines the concept of automation. A better approach is to provide a password file that contains the password required by the encrypted file. The Ansible Vault password file is kept in a secure location and Ansible reads the file for the password needed to decrypt the file used by the playbook
During playbook runtime, the file is referenced using the
--vault-pass-file option followed by the path of the file containing the password. In this example, we have a password file at
The command would appear as follows when running the playbook.
sudo ansible-playbook -i ansible/inventory sample-playbook.yaml –vault-pass-file ~/secrets/vault_pass.txt
From the output, you can see that the playbook runs without any password prompts which is a better way of decrying files during runtime as opposed to manually typing the password.
Ansible Vault is indeed a useful tool in encrypting and decrypting files used in Ansible Playbooks. Take a look at Ansible Vault Docs, in case you want to learn further details, and for more reading on Ansible, check out our detailed and comprehensive Ansible tutorials.