Learn how to - Ansible Vault Cheat Sheet / Reference guide

Felix Williams Automation How to Linux Tutorials March 12, 2023

Learn how to – Ansible Vault Cheat Sheet / Reference guide.

How do I encrypt sensitive data with Ansible Vault?, How to secure Ansible Playbooks with Vault?, How to use Ansible Vault on my projects?. This guide has been done as a reference guide/cheat sheet for Ansible enthusiasts using Vault to ensure data is encrypted and secured when working on Ansible Projects.

Ansible has proven to be the most used and Loved configuration management tool for Developers and SysAdmins of all classes. With more adoption arises security concerns. To keep your sensitive information such as passwords or private keys safe you need Vault. The vault-encrypted data is automatically decrypted at runtime.

Ansible is a requirement for this guide. Ensure Ansible is installed on your system, which provides ansible-vault command-line tool that we’ll use in this entire guide. Before you get started, set a default editor for Ansible Vault.

### For Bash ###
echo "export EDITOR=vim" >> ~/.bashrc
source ~/.bashrc

### For Zsh ###
echo "export EDITOR=vim" >> ~/.zshrc
source ~/.zshrc

Replace vim with your favorite editor.

Install Ansible / Ansible Vault

The easiest way to Install Ansible on Linux and most Unix systems is via Ansible package manager – pip.

Install Python3

### RHEL based systems ###
sudo yum -y install epel-release
sudo yum -y install python3

### Debian based systems ###
sudo apt update && sudo apt install python3

Install pip3:

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

### Global install
sudo python3 get-pip.py

# Local user install
python3 get-pip.py --user

If you have Python version <3.7, the use:

wget https://bootstrap.pypa.io/pip/3.6/get-pip.py

Once pip3 has been installed, use it to install Ansible.

### Global install
sudo pip3 install ansible

# Local user install
pip3 install --user ansible

Add ~/.local/bin/ to your PATH.

echo 'PATH=~/.local/bin:$PATH' >> ~/.bashrc
source  ~/.bashrc

Using Ansible Vault

In this section, we’ll see many examples on how to use Ansible Vault. The ansible-vault command is used to manage encrypted content within Ansible. With it you create, edit, view and decrypt encrypted files.

Example 1: Create a new encrypted file

To create a new file that’s encrypted with Vault, use the create option and append the name of the file. For example, to create an encrypted YAML file called create_users.yml which will contain sensitive data, run:

ansible-vault create create_users.yml

You will be prompted to enter and confirm secure password:

New Vault password: 
Confirm New Vault password:

Ansible will then open an editing window for you to input your desired contents.

Example 2: Encrypt existing file

For existing files, use the ansible-vault encrypt command to set password.

$ echo "SecurePassword" > passwords.txt
$ ansible-vault encrypt passwords.txt
New Vault password: 
Confirm New Vault password: 
Encryption successful

This will replace the unencrypted file with encrypted one.

$ cat passwords.txt
$ANSIBLE_VAULT;1.1;AES256
30653331363933343563396461623132623437636232373462646538333736666531333732353033
3134666133626361623330376534336632633462643233650a386137626561663938313463396236
63376166313530636461306636623638623835666263326431646333663665313563373766643039
6337393539396562360a643237346262353461303738663134383739366532613538653635383466
3634

Example 3: Edit encrypted file

To edit an encrypted file, use the command ansible-vault edit command.

ansible-vault edit passwords.yml

This will ask you to input file password.

Vault password:

Example 4: Update encryption password

You can always update encryption password by using the ansible-vault rekey command.

$ ansible-vault rekey create_users.yml
Vault password: 
New Vault password: 
Confirm New Vault password: 
Rekey successful

Input the old password and new one to set when prompted. Once updated, the file will be accessible using the new password.

Example 5: View Ansible encrypted file

You can view the contents of vault-encrypted file without opening window editor. For this you’ll use the command ansible-vault view .

ansible-vault view create_users.yml

You should be asked to input file password before contents can be displayed.

Vault password:
Secret information

Example 6: Decrypt Vault Encrypted Files

If you no longer need encryption, you can decrypt a vault encrypted file using the ansible-vault decrypt command.

ansible-vault decrypt myfile.yml

Provide encryption password for the file.

Vault password:
Decryption successful

You will be able to see the actual contents of the file after decryption.

Example 7: Execute Ansible with Vault-Encrypted Files

Once you encrypt your sensitive data, you obviously want to run an Ansible playbook which references encrypted data in some way. The ansible and ansible-playbook commands can decrypt vault-protected files if the correct password is provided.

Using password prompt

For playbook execution, pass the --ask-vault-pass flag.

ansible-playbook --ask-vault-pass <vault-encrypted-playbook-file>.yaml

For Ansible greater or equals to 2.4, you can use –vault-id @prompt flag.

See example below.

$ ansible-playbook --ask-vault-pass -i hosts osp-pre.yml 
Vault password: 

PLAY [Run presetup on OSP nodes] ******************************************************************************************************************

TASK [Gathering Facts] ****************************************************************************************************************************
...................................................................................

$ ansible-playbook -i hosts osp-pre.yml --vault-id @prompt
Vault password (default):

Using Password file

If you want to avoid interactive password prompt during playbook execution, then consider using Ansible Vault with a Password File.

Create password file.

echo 'MyStrongVaulPassword' > .ansible_vault_pass

For guys using Version Control systems such as git, consider adding the .ansible_vault_pass file to list of ignored files.

echo '.ansible_vault_pass' >> .gitignore

Now reference password file when running ansible or ansible-playbook command.

ansible --vault-password-file=.ansible_vault_pass ...
ansible-playbook --vault-password-file=.ansible_vault_pass ....

Example:

$ ansible-playbook --vault-password-file=.ansible_vault_pass -i hosts osp-pre.yml 
PLAY [Run presetup on OSP nodes] ******************************************************************************************************************

TASK [Gathering Facts] ****************************************************************************************************************************

As seen above, there is no prompt to input password file.

Set ANSIBLE_VAULT_PASSWORD_FILE Environment variable

If you don’t like providing password flag or using interactive password prompt, you can configure Ansible to read the Password file automatically. This is achieved by setting the ANSIBLE_VAULT_PASSWORD_FILE environment variable with the path to the password file:

export ANSIBLE_VAULT_PASSWORD_FILE=./.ansible_vault_pass

To persist the configuration, set it in your local ansible.cfg file.

$ vim ansible.cfg
[defaults]
........
vault_password_file = ./.ansible_vault_pass

Ansible will use the configure password for all encrypt and create operations.

Example 8: Encrypt only sensitive variables

In ideal automation world with collaboration, you’ll only want to encrypt sensitive data such as Database passwords, API keys, user credentials e.t.c.

Create encrypted variables file.

$ vim vars/vault.yml
vault_db_pass: MyStrongPassword

$ ansible-vault encrypt vars/vault.yml
New Vault password: 
Confirm New Vault password: 
Encryption successful

Confirm it is encrypted.

$ cat vars/vault.yml 
$ANSIBLE_VAULT;1.1;AES256
62383961353832333263356333356465633635633731393039303834623832626162613235343930
6238663730366237616639326233393361626639616136300a393665326434633438613436316630
61656261616132366436646434393833613064326531346631666630616535663535353038666135
3732333338313739340a656434633336666662393161393663303662616264643364313630383163
30643763323038396161316339663037353632626462626233363836346461656238393035623533
6531353930326133656165326130303661303965316464306330

We will then define other unencrypted Variables and reference encrypted in Vault Variables.

$ vim vars/plain.yml
db_user: learnhowto
db_port: 3306
db_pass: "{{ vault_db_pass }}"

Note that we used Jinja2 templating to reference the variable defined in the vault-protected file.

Create Playbook file.

 $ vim vault.yml 
---
- name: Create users
  hosts: localhost
  tasks:
    - name: Include vars
      include_vars:
        dir: vars

    - name: Generate dummy variables data
      blockinfile:
        path: /tmp/vault
        block:
            Database user: "{{ db_user }}"
            Database Port: "{{ db_port }}"
            Database Password: "{{ db_pass }}"

Run playbook:

$ ansible-playbook --connection=local vault.yml --ask-vault-pass
Vault password: 

PLAY [Create users] *******************************************************************************************************************************

TASK [Gathering Facts] ****************************************************************************************************************************
ok: [localhost]

TASK [Include vars] *******************************************************************************************************************************
ok: [localhost]

TASK [Generate dummy variables data] **************************************************************************************************************
changed: [localhost]

PLAY RECAP ****************************************************************************************************************************************
localhost                  : ok=3    changed=1    unreachable=0    failed=0

Let’s check the contents of created file.

$ cat /tmp/vault
# BEGIN ANSIBLE MANAGED BLOCK
Database user: "learnhowto"
Database Port: "3306"
Database Password: "MyStrongPassword"
# END ANSIBLE MANAGED BLOCK

Recommended Ansible Books:

Best Books To learn Docker and Ansible Automation

Conclusion

In this guide, we demonstrated how you can use Ansible Vault to encrypt sensitive variables and data so you can safely share your projects without compromising security.

Cart

Learn how to – Ansible Vault Cheat Sheet / Reference guide