06 July, 2021

How to encrypt files with Ansible Vault

ansible

Ansible Vault

Ansible Vault encrypts variables or complete files so sensitive values do not sit in plaintext alongside your playbooks, variable files, or roles.

This example uses Ansible Core 2.20.1 and a named Vault ID, unixtutorial. A Vault ID is a label that helps Ansible select the right password when a project uses more than one encrypted file or password.

What files should you encrypt?

I use Ansible Vault for files that must exist in an automation repository but should not be readable as ordinary text. Common examples include:

passwords and API credentials;
private keys and pre-shared VPN keys;
application secrets in variable files;
internal identifiers that reveal infrastructure details.

Encryption does not make it safe to publish every secret. Limit access to the repository and keep the Vault password in a password manager. If you lose the password, Ansible cannot recover the original contents.

Create the sample file

This walkthrough encrypts a small YAML variable file:

greys@ubuntu $ cat group_vars.yml
vault_word: tutorial
vault_identifier: unixtutorial@prompt

The unixtutorial@prompt value inside this sample is only text for the walkthrough. The actual Vault ID is supplied to ansible-vault on the command line.

Encrypt the file

Run ansible-vault encrypt and tell Ansible to prompt for the password associated with the unixtutorial Vault ID:

greys@ubuntu $ ansible-vault encrypt group_vars.yml --vault-id unixtutorial@prompt
New vault password (unixtutorial):
Confirm new vault password (unixtutorial):
Encryption successful

The command replaces group_vars.yml with encrypted data. Its first line identifies the Ansible Vault format, cipher, and Vault ID label:

greys@ubuntu $ head -1 group_vars.yml
$ANSIBLE_VAULT;1.2;AES256;unixtutorial

The file no longer contains vault_word: tutorial in plaintext. The Vault ID label remains visible, but the password does not.

Encrypt with a single Vault password

If you do not need named Vault IDs, Ansible can use a single prompted password:

greys@ubuntu $ ansible-vault encrypt group_vars.yml --ask-vault-pass

Named IDs become useful when development, staging, and production secrets use different passwords.

Use the encrypted file

Ansible playbooks can request the Vault password at runtime:

greys@ubuntu $ ansible-playbook site.yml --ask-vault-pass

For a named Vault ID, use:

greys@ubuntu $ ansible-playbook site.yml --vault-id unixtutorial@prompt

Do not commit a Vault password file to the repository. If you automate password retrieval, restrict its permissions and use an appropriate secret manager.

Decrypt or inspect the file

To restore the plaintext file, follow How to decrypt files with Ansible Vault. That guide also shows ansible-vault view, which reads the secret without leaving the file decrypted on disk.