Ansible Vault

Learn how to encrypt sensitive data like passwords, and SSH private keys

Ansible Vault is a powerful feature that allows you to encrypt sensitive data — like passwords, API keys and SSH private keys — so you can safely commit them to GitHub while keeping them secure. The Ansible Vault is kept on your Ansible Control and is shared across your playbooks and hosts to:

• Encrypting variables, files, or strings you use across your Ansible Playbooks

• Protecting secrets like validator keypair sets used to setup validators

A full documentation of the Ansible Vault feature is available in Ansible's official docs.

Useful Commands

Command	Description
ansible-vault view	Views encrypted content (after entering the password)
ansible-vault edit	Opens an editor to modify encrypted files securely
ansible-vault decrypt	Converts a file back to plain text
--ask-vault-pass	Prompts for a password at runtime
--vault-password-file	Reads the vault pass from a secure file

Vault password

The simplest way to access encrypted assets stored in the Ansible Vault, is by sharing passwords to each of the vault items. We recommend using a password manager, like 1Password, to manage shared passwords across your team.

Best Practices

1. Store only what’s necessary in Vault (not full playbooks).

2. Use one vault file per environment or group to avoid the proliferation of vaults everywhere.

3. Rotate and manage vault keys and passwords securely using a well known password manager, like 1Password or Keeper.

4. Use tools like ansible-vault rekey to change passwords without decrypting.

Store a secret item

Imagine you have an aws_secret_access_key = "Follow the white rabbit" that you wish to put in the vault.

# from your Ansible Control server, create a vault file
ansible-vault create /ansible/vault/group_vars/all/vault.yml

You’ll be prompted to enter a vault password (use 1Password here) and then dropped into a text editor, where you'll paste this:

aws_secret_access_key = "Follow the white rabbit"

Save and exit.

At this point your aws_secret_access_key is stored as a variable in the vault.yml vault, which is shared by all hosts, and safely encrypted using your 1Password password. You can commit this file to GitHub without a problem.

Using in a playbook or role

Ansible will auto-load group_vars/all/vault.yml if the host is in the all group — which it always is. YOu can also explicitly include it:

vars_files:
  - group_vars/all/vault.yml

To use in your playbook simply use the variable name as any other variable:

- name: Show AWS Secret Key (don't actually do this 😅)
  debug:
    msg: "My AWS key is {{ aws_secret_access_key }}"

When running your playbook, speficy the --ask-vault-pass to get prompted for the password at runtime:

ansible-playbook playbook.yml --ask-vault-pass

Change Vault Password

To change the password on your existing Vault file — like group_vars/all/vault.yml — use the ansible-vault rekey command.

ansible-vault rekey group_vars/all/vault.yml

You’ll be prompted to:

1. Enter the current vault password (to unlock it)

2. Enter the new password

3. Confirm the new password

That’s it! The file is now encrypted with the new password.