diff --git a/docsite/rst/playbooks_best_practices.rst b/docsite/rst/playbooks_best_practices.rst index 343d4bcc22d..9b0651fcd2a 100644 --- a/docsite/rst/playbooks_best_practices.rst +++ b/docsite/rst/playbooks_best_practices.rst @@ -421,6 +421,18 @@ Use version control. Keep your playbooks and inventory file in git to them. This way you have an audit trail describing when and why you changed the rules that are automating your infrastructure. +.. _best_practices_for_variables_and_vaults: + +Variables and Vaults +++++++++++++++++++++++++++++++++++++++++ + +For general maintenance, it is often easier to use ``grep``, or similar tools, to find variables in your Ansible setup. Since vaults obscure these variables, it is best to work with a layer of indirection. When running a playbook, Ansible finds the variables in the unencrypted file and all sensitive variables come from the encrypted file. + +A best practice approach for this is to start with a ``group_vars/`` subdirectory named after the group. Inside of this subdirectory, create two files named ``vars`` and ``vault``. Inside of the ``vars`` file, define all of the variables needed, including any sensitive ones. Next, copy all of the sensitive variables over to the ``vault`` file and prefix these variables with ``vault_``. You should adjust the variables in the ``vars`` file to point to the matching ``vault_`` variables and ensure that the ``vault`` file is vault encrypted. + +This best practice has no limit on the amount of variable and vault files or their names. + + .. seealso:: :doc:`YAMLSyntax` diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst index cf4fd7fb696..4428d3e75d1 100644 --- a/docsite/rst/playbooks_variables.rst +++ b/docsite/rst/playbooks_variables.rst @@ -21,6 +21,8 @@ and the ``when`` conditional can also be used with variables, and to help manage It's highly recommended that you consult the ansible-examples github repository to see a lot of examples of variables put to use. +For best practices advice, refer to :ref:`best_practices_for_variables_and_vaults` in the *Best Practices* chapter. + .. _valid_variable_names: What Makes A Valid Variable Name diff --git a/docsite/rst/playbooks_vault.rst b/docsite/rst/playbooks_vault.rst index 9dce71e2f8b..01836f796fd 100644 --- a/docsite/rst/playbooks_vault.rst +++ b/docsite/rst/playbooks_vault.rst @@ -7,6 +7,8 @@ New in Ansible 1.5, "Vault" is a feature of ansible that allows keeping sensitiv To enable this feature, a command line tool, `ansible-vault` is used to edit files, and a command line flag `--ask-vault-pass` or `--vault-password-file` is used. Alternately, you may specify the location of a password file or command Ansible to always prompt for the password in your ansible.cfg file. These options require no command line flag usage. +For best practices advice, refer to :ref:`best_practices_for_variables_and_vaults`. + .. _what_can_be_encrypted_with_vault: What Can Be Encrypted With Vault