Merge pull request #12764 from docschick/docschick-fixes

vault and variables best practices info added, edited, and referenced

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`

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

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