Vault
Some Ansible variables contain sensitive data such as passwords. Trellis keeps these variable definitions in separate files named vault.yml
. We strongly recommend that you encrypt these vault.yml
files using Ansible Vault to avoid exposing sensitive data in your project repo. Your Trellis commands will be exactly the same as before enabling vault, not requiring any extra flags.
To briefly demonstrate what vault does, consider this example vault.yml
file.
You should replace the example_password
then encrypt the file with Ansible Vault before committing it to your repo. The data would be safe in your repo because the encrypted file would look like this:
Steps to enable Ansible Vault
If you have unencrypted vault.yml
files in your project's git history (e.g., passwords in plain text), you will most likely want to change the variable values in your vault.yml
files before encrypting them and committing them to your repo.
Encrypt files
trellis-cli
automatically generates your vault files and a vault password, but does not encrypt your vaults. To encrypt vaults created by trellis-cli
run the following from any directory within your project:
Other vault commands
trellis-cli
provides a few basic commands that mirror with the official Ansible Vault ones.
-
trellis vault encrypt <args>
-
trellis vault view <args>
-
trellis vault edit <args>
-
trellis vault decrypt <args>
-- Avoid using thedecrypt
command. If your intention is to view or edit an encrypted file, use theview
oredit
commands instead. Any time you decrypt a file, you risk forgetting to re-encrypt the file before committing changes to your repo.
Run trellis vault
to see usage details.
Working with vault variables
Here are a few tips for working with variables and vault in Trellis.
- Variables with sensitive data such as passwords are defined in files named
vault.yml
. - Each environment has its own
vault.yml
file:group_vars/<environment>/vault.yml
. - There is also one
vault.yml
file applicable to all environments:group_vars/all/vault.yml
. - Variables named with the
vault_
prefix are defined in thevault.yml
files. - To view or edit an encrypted
vault.yml
file, use eithertrellis vault view <file>
ortrellis vault edit <file>
. Avoid using thedecrypt
command. Any time you decrypt a file, you risk forgetting to re-encrypt the file before committing changes to your repo. You may want to employ a pre-commit hook (example) for added prevention.
Sharing a project with vault-encrypted files
Your repo with vault-encrypted files is secure from anyone being able to see or use the sensitive data in the vault.yml
files. To grant a colleague access to the data, you will need to give your colleague your vault password to use in repeating the two password steps in the Steps to Enable Ansible Vault above. It is still recommended to always keep your project in a private repo.
Disabling Ansible Vault
It is not recommended to disable Ansible Vault but you can disable it at any time. Simply run ansible-vault decrypt <file1> <file2> <etc>
. If you then commit the unencrypted files to your repo, the sensitive data will be in your repo in plain text and will be difficult to remove from the git history. If you re-enable vault in the future, you may want to change all the sensitive data, encrypt with vault, then commit the revised and encrypted vault.yml
files to your repo.
Storing your password
Without your password, either entered as a string or stored in your vault_password_file
file (usually .vault_pass
and configured in the ansible.cfg
file), you will not be able to access the encrypted files. The vault_password_file
should not ever be publicly accessible, or committed to version control. It's a good practice to backup this file on another physical or virtual drive, ideally also encrypted.
Access Recovery
Should you lose access to your vault password, you you can either spin up a new server, or recreate or regenerate the group_vars/(environment)/vault.yml
files and, on the servers, manually update the following to match new vault strings:
- admin root (sudo) password
-
sudo passwd admin
-
- root mysql password
-
UPDATE mysql.user SET Password=PASSWORD('password_in_vault_file') WHERE USER='root' AND Host='localhost';
-
flush privileges;
-
- wordpress database passwords
-
UPDATE mysql.user SET Password=PASSWORD('password_in_vault_file') WHERE USER='example_com' AND Host='localhost';
-
flush privileges;
-
Additional resources
ansible-toolkit provides a atk-git-diff
command that allows you to do a git diff
on encrypted files.