Ansible vault tools
Ansible vault is a great tool for managing secrets for Ansible playbooks, but dealing with the vault can be a pain. This repo contains instructions and helper scripts to reduce that pain.
This project provides some helper scripts for dealing with ansible vault files.
These scripts can be installed by running
make install, which may or may not
require root permissions.
There is also a
make uninstall, in case you change your mind.
Vault Filename Conventions
In order for git to know when to use the ansible vault tools for decrypting
files, it needs to know when it's dealing with a vault file. To do this, you
will need to have a consistent naming convention for your vault files. I
vault.yml (if you like having a single vault) or
*.vault.yml (if you like having lots of vaults).
The pattern for your vault files can be configured in one of three places for git.
./.gitattributes- per project, checked into git
./.git/info/attributes- per project, not checked in
$HOME/.config/git/attributes- per user config
Wherever you chose to put it, the configuration is the same:
# gitattributes vault.yml diff=ansible-vault merge=ansible-vault *.vault.yml diff=ansible-vault merge=ansible-vault
The configuration for the ansible-vault diff handler goes into
# gitconfig [diff "ansible-vault"] textconv = ansible-vault view # Do not cache the vault contents cachetextconv = false
With the textconv settings above, this also allows you to grep into vaulted
files. To do this, you need to pass the
--textconv option to
$ git grep --textconv super_secret group_vars/all/vault.yml:super_secret: tell no one
You can similarly configure a merge driver for use with ansible vault files. The
provided merge driver uses the underlying
git merge-files command to merge the
unencrypted contents of the vault files being merged. If there are any merge
$EDITOR is opened allowing you to resolve the conflict before the
merged file is re-encrypted.
# gitconfig [merge "ansible-vault"] name = ansible-vault merge driver driver = /usr/local/bin/ansible-vault-merge -- %O %A %B %P
ansible vault password caching
Ansible vault allows you to configure the location of the vault password file, which can go into any of Ansible's configuration files.
./ansible.cfg- per project configuration
$HOME/.ansible.cfg- per user configuration
/etc/ansible/ansible.cfg- per system configuration
# ansible.cfg [defaults] vault_password_file = /path/to/vault_password_file
While normally the vault password file is a file that contains the plain text vault password (which seems like a bad idea), this password file could be an executable script, which can use a tool with good password caching (like gpg) to decrypt the password file. Please look up the gpg-agent for instructions on how to use it effectively.
gpg-vault-password-file can be used to create a script that can be
used to store the vault password in a GPG encrypted file. This will create an
executable script in the location given, and the vault password encrypted with
the default self key.
Used in this manner,
ansible-vault will prompt for your GPG password when
used, which will be cached for some period of time.
$ gpg-vault-password-file /path/to/vault_password_file