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

This work fulfills PR #11799. Moved the content out of the vault file,
into best practices, edited it, then referenced it from variables and
vaults content files.

3 files changed, 16 insertions, 0 deletions

diff --git a/docsite/rst/playbooks_best_practices.rst b/docsite/rst/playbooks_best_practices.rst
index 343d4bcc22..9b0651fcd2 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 cf4fd7fb69..4428d3e75d 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 9dce71e2f8..01836f796f 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