How To Use Ansible Vault To Protect Sensitive Playbook Data

In This Article will explore Ansible Vault as a mechanism for keeping your sensitive values and secrets secure in your playbooks and other Ansible files. We will investigate different options for working with encrypted content and password management options.

Objectives:

After completing this section, you should be able to encrypt sensitive variables using Ansible Vault, and run playbooks that reference Vault-encrypted variable files.

What is Ansible Valut?

Ansible may need access to sensitive data such as passwords or API keys in order to configure managed hosts. Normally, this information might be stored as plain text in inventory variables or other Ansible files. In that case, however, any user with access to the Ansible files or a version control system which stores the Ansible files would have access to this sensitive data. This poses an obvious security risk. Ansible Vault, which is included with Ansible, can be used to encrypt and decrypt any structured data file used by Ansible. To use Ansible Vault, a command-line tool named ansible-vault is used to create, edit, encrypt, decrypt, and view files.

How To Create An Encrypted File?

To create a new encrypted file, use the ansible-vault create filename command. The command prompts for the new vault password and then opens a file using the default editor, vi. You can set and export the EDITOR environment variable to specify a different default editor by setting and exporting. For example, to set the default editor to nano, export EDITOR=nano.

[student@demo ~]$ ansible-vault create secret.yml
New Vault password: redhat
Confirm New Vault password: redhat

Instead of entering the vault password through standard input, you can use a vault password file to store the vault password. You need to carefully protect this file using file permissions and other means.

[student@demo ~]$ ansible-vault create --vault-password-file=vault-pass secret.yml

The cipher used to protect files is AES256 in recent versions of Ansible, but files encrypted with older versions may still use 128-bit AES.

How To View an Encrypted File ?

You can use the ansible-vault view filename command to view an Ansible Vault-encrypted file without opening it for editing.

How To Edit An Existing Encrypted File?

To edit an existing encrypted file, Ansible Vault provides the ansible-vault edit filename command. This command decrypts the file to a temporary file and allows you to edit it. When saved, it copies the content and removes the temporary file.

Note: The edit subcommand always rewrites the file, so you should only use it when making changes. This can have implications when the file is kept under version control. You should always use the view subcommand to view the file’s contents without making changes.

How To Encrypt an Existing File?

To encrypt a file that already exists, use the ansible-vault encrypt filename command. This command can take the names of multiple files to be encrypted as arguments.

Use the –output=OUTPUT_FILE option to save the encrypted file with a new name. You can only use one input file with the –output option.

How To Decrypt an Existing File:

An existing encrypted file can be permanently decrypted by using the ansible-vault decrypt filename command. When decrypting a single file, you can use the –output option to save the decrypted file under a different name.

How To Change the Password of an Encrypted File?

You can use the ansible-vault rekey filename command to change the password of an encrypted file. This command can rekey multiple data files at once. It prompts for the original password and then the new password. When using a vault password file, use the –new-vault-password-file option:

[student@demo ~]$ ansible-vault rekey \
> --new-vault-password-file=NEW_VAULT_PASSWORD_FILE secret.yml

Playbook and Ansible Vault:

To run a playbook that accesses files encrypted with Ansible Vault, you need to provide the encryption password to the ansible-playbook command. If you do not provide the password, the playbook returns an error:

[student@demo ~]$ ansible-playbook site.yml
ERROR: A vault password must be specified to decrypt vars/api_key.yml

To provide the vault password to the playbook, use the –vault-id option. For example, to provide the vault password interactively, use –vault-id @prompt as illustrated in the following example:

[student@demo ~]$ ansible-playbook --vault-id @prompt site.yml
Vault password (default): redhat

IMPORTANT: If you are using a release of Ansible earlier than version 2.4, you need to use the — ask-vault-pass option to interactively provide the vault password. You can still use this option if all vault-encrypted files used by the playbook were encrypted with the same password.

[student@demo ~]$ ansible-playbook --ask-vault-pass site.yml
Vault password: redhat

Alternatively, you can use the –vault-password-file option to specify a file that stores the encryption password in plain text. The password should be a string stored as a single line in the file. Because that file contains the sensitive plain text password, it is vital that it be protected through file permissions and other security measures.

[student@demo ~]$ ansible-playbook --vault-password-file=vault-pw-file site.yml

You can also use the ANSIBLE_VAULT_PASSWORD_FILE environment variable to specify the default location of the password file.

IMPORTANT:

Starting with Ansible 2.4, you can use multiple Ansible Vault passwords with ansible-playbook. To use multiple passwords, pass multiple –vault-id or — vault-password-file options to the ansible-playbook command.

[student@demo ~]$ ansible-playbook \
> --vault-id one@prompt --vault-id two@prompt site.yml
Vault password (one):
Vault password (two):
...output omitted...

The vault IDs one and two preceding @prompt can be anything and you can even omit them entirely. If you use the –vault-id id option when you encrypt a file with ansible-vault command, however, when you run ansible-playbook then the password for the matching ID is tried before any others. If it does not match, the other passwords you provided will be tried next. The vault ID @prompt with no ID is actually shorthand for default@prompt, which means to prompt for the password for vault ID default.

Best Practices for Managing Variable Files

To simplify your workflow, keep sensitive and non-sensitive variables in separate files. You should protect files containing secrets using the ansible-vault command.

The best way to manage variables is by creating group_vars and host_vars directories at the playbook level. While you can use single files, using directories for each group or host offers more flexibility.

Using Directories for Better Security

By using a directory structure, you can split your host or group data into multiple files:

vars: Used for plain-text, non-sensitive variables.
vault: Used exclusively for sensitive data encrypted by Ansible Vault.

Example Structure:

Plaintext 
├── group_vars/
│   └── webservers/
│       └── vars
├── host_vars/
│   └── demo.example.com/
│       ├── vars
│       └── vault (Encrypted)

Playbook Variables and Vault IDs

You can also protect playbook variables using the vars_files directive. This is highly effective because playbook variables take precedence over inventory variables.

If you use multiple vault passwords, assign a vault ID to each encrypted file. This allows Ansible to select the correct password immediately, making the decryption process much faster than trying every password in your list.

You can refer also Ansible public documentation https://docs.ansible.com/projects/ansible/latest/vault_guide/vault.html to get more information about Ansible Vault.

Please visit our official website https://linuxgktech.com/ansible/ to know more about Ansible.