Chapter 3. Ansible vault
You can use Ansible vault to encrypt sensitive data, such as passwords and API keys, in your playbooks.
Storing sensitive data in plain text in variables or other Ansible-compatible files is a security risk because any user with access to those files can read the sensitive data.
With Ansible vault, you can encrypt, decrypt, view, and edit sensitive information. They could be included as:
- Inserted variable files in an Ansible Playbook
- Host and group variables
- Variable files passed as arguments when executing the playbook
- Variables defined in Ansible roles
You can use Ansible vault to securely manage individual variables, entire files, or even structured data like YAML files. This data can then be safely stored in a version control system or shared with team members without exposing sensitive information.
Files are protected with symmetric encryption of the Advanced Encryption Standard (AES256), where a single password or passphrase is used both to encrypt and decrypt the data. Note that the way this is done has not been formally audited by a third party.
To simplify management, it makes sense to set up your Ansible project so that sensitive variables and all other variables are kept in separate files, or directories. Then you can protect the files containing sensitive variables with the ansible-vault command.
- Creating an encrypted file
The following command prompts you for a new vault password. Then it opens a file for storing sensitive variables using the default editor.
ansible-vault create vault.yml New Vault password: <vault_password> Confirm New Vault password: <vault_password>
# ansible-vault create vault.yml New Vault password: <vault_password> Confirm New Vault password: <vault_password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Viewing an encrypted file
The following command prompts you for your existing vault password. Then it displays the sensitive contents of an already encrypted file.
ansible-vault view vault.yml Vault password: <vault_password> my_secret: "yJJvPqhsiusmmPPZdnjndkdnYNDjdj782meUZcw"
# ansible-vault view vault.yml Vault password: <vault_password> my_secret: "yJJvPqhsiusmmPPZdnjndkdnYNDjdj782meUZcw"Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Editing an encrypted file
The following command prompts you for your existing vault password. Then it opens the already encrypted file for you to update the sensitive variables using the default editor.
ansible-vault edit vault.yml Vault password: <vault_password>
# ansible-vault edit vault.yml Vault password: <vault_password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Encrypting an existing file
The following command prompts you for a new vault password. Then it encrypts an existing unencrypted file.
ansible-vault encrypt vault.yml New Vault password: <vault_password> Confirm New Vault password: <vault_password> Encryption successful
# ansible-vault encrypt vault.yml New Vault password: <vault_password> Confirm New Vault password: <vault_password> Encryption successfulCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Decrypting an existing file
The following command prompts you for your existing vault password. Then it decrypts an existing encrypted file.
ansible-vault decrypt vault.yml Vault password: <vault_password> Decryption successful
# ansible-vault decrypt vault.yml Vault password: <vault_password> Decryption successfulCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Changing the password of an encrypted file
The following command prompts you for your original vault password, then for the new vault password.
ansible-vault rekey vault.yml Vault password: <vault_password> New Vault password: <vault_password> Confirm New Vault password: <vault_password> Rekey successful
# ansible-vault rekey vault.yml Vault password: <vault_password> New Vault password: <vault_password> Confirm New Vault password: <vault_password> Rekey successfulCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Basic application of Ansible vault variables in a playbook
Copy to Clipboard Copied! Toggle word wrap Toggle overflow You read-in the file with variables (
vault.yml) in thevars_filessection of your Ansible Playbook, and you use the curly brackets the same way you would do with your ordinary variables. Then you either run the playbook with theansible-playbook --ask-vault-passcommand and you enter the password manually. Or you save the password in a separate file and you run the playbook with theansible-playbook --vault-password-file /path/to/my/vault-password-filecommand.