added docs for vault and made trigger shorter: !vault (#20985)

* added docs for vault and made trigger shorter: !vault

* added single var valuting

* Update playbooks_vault.rst

Edit pass for spelling and grammar. Ship it!

* Update playbooks_vault.rst

Typo fixes.

CHANGELOG.md

@@ -4,6 +4,7 @@ Ansible Changes By Release
 ## 2.3 TBD - ACTIVE DEVELOPMENT
 
 ###Major Changes:
+* Documented and renamed the previously released 'single var vaulting' feature, allowing user to use vault encryption for single variables in a normal YAML vars file.
 
 ###Minor Changes:
 * The version and release facts for OpenBSD hosts were reversed.  This has been

docs/docsite/rst/playbooks_vault.rst

@@ -20,6 +20,8 @@ Ansible tasks, handlers, and so on are also data so these can be encrypted with
 
 The vault feature can also encrypt arbitrary files, even binary files.  If a vault-encrypted file is given as the `src` argument to the `copy` module, the file will be placed at the destination on the target host decrypted (assuming a valid vault password is supplied when running the play).
 
+As of version 2.3, Ansible also supports encrypting single values inside a YAML file, using the `!vault` tag to let YAML and Ansible know it uses special processing. This feature is covered in more details below.
+
 .. _creating_files:
 
 Creating Encrypted Files
@@ -115,6 +117,28 @@ This is something you may wish to do if using Ansible from a continuous integrat
 
 (The `--vault-password-file` option can also be used with the :ref:`ansible-pull` command if you wish, though this would require distributing the keys to your nodes, so understand the implications -- vault is more intended for push mode).
 
+
+.. _single_encryptd_variable:
+
+Single Encrypted Variable
+`````````````````````````
+
+As of version 2.3, Ansible can now use a vaulted variable that lives in an otherwise 'clear text' YAML file::
+
+    notsecret: myvalue
+    mysecret: !vault |
+              $ANSIBLE_VAULT;1.1;AES256
+              66386439653236336462626566653063336164663966303231363934653561363964363833313662
+              6431626536303530376336343832656537303632313433360a626438346336353331386135323734
+              62656361653630373231613662633962316233633936396165386439616533353965373339616234
+              3430613539666330390a313736323265656432366236633330313963326365653937323833366536
+              34623731376664623134383463316265643436343438623266623965636363326136
+    other_plain_text: othervalue
+
+
+This vaulted variable be decrypted with the supplied vault secret and used as a normal variable. The `ansible-vault` command line supports stdin and stdout for encrypting data on the fly, which can be used from your favorite editor to create these vaulted variables; you just have to be sure to add the `!vault` tag so both Ansible and YAML are aware of the need to decrypt. The `|` is also required, as vault encryption results in a multi-line string.
+
+
 .. _speeding_up_vault:
 
 Speeding Up Vault Operations

lib/ansible/parsing/yaml/constructor.py

@@ -156,6 +156,4 @@ AnsibleConstructor.add_constructor(
     u'!unsafe',
     AnsibleConstructor.construct_yaml_unsafe)
 
-AnsibleConstructor.add_constructor(
+AnsibleConstructor.add_constructor(u'!vault', AnsibleConstructor.construct_vault_encrypted_unicode)
-    u'!vault-encrypted',
-    AnsibleConstructor.construct_vault_encrypted_unicode)

lib/ansible/parsing/yaml/dumper.py

@@ -40,7 +40,7 @@ def represent_hostvars(self, data):
 
 # Note: only want to represent the encrypted data
 def represent_vault_encrypted_unicode(self, data):
-    return self.represent_scalar(u'!vault-encrypted', data._ciphertext.decode(), style='|')
+    return self.represent_scalar(u'!vault', data._ciphertext.decode(), style='|')
 
 if PY3:
     represent_unicode = yaml.representer.SafeRepresenter.represent_str

lib/ansible/parsing/yaml/objects.py

@@ -73,7 +73,7 @@ class AnsibleSequence(AnsibleBaseYAMLObject, list):
 class AnsibleVaultEncryptedUnicode(yaml.YAMLObject, AnsibleUnicode):
     __UNSAFE__ = True
     __ENCRYPTED__ = True
-    yaml_tag = u'!vault-encrypted'
+    yaml_tag = u'!vault'
 
     @classmethod
     def from_plaintext(cls, seq, vault):

test/integration/targets/vault/roles/test_vault_embedded/vars/main.yml

@@ -1,14 +1,14 @@
 # If you use normal 'ansible-vault create' or edit, files always have at least one new line
 # so c&p from a vault encrypted that wasn't specifically created sans new line ends up with one.
 # (specifically created, as in 'echo -n "just one line" > my_secret.yml'
-vault_encrypted_var: !vault-encrypted |
+vault_encrypted_var: !vault |
               $ANSIBLE_VAULT;1.1;AES256
               66386439653236336462626566653063336164663966303231363934653561363964363833313662
               6431626536303530376336343832656537303632313433360a626438346336353331386135323734
               62656361653630373231613662633962316233633936396165386439616533353965373339616234
               3430613539666330390a313736323265656432366236633330313963326365653937323833366536
               34623731376664623134383463316265643436343438623266623965636363326136
-vault_encrypted_one_line_var: !vault-encrypted |
+vault_encrypted_one_line_var: !vault |
                               $ANSIBLE_VAULT;1.1;AES256
                               33363965326261303234626463623963633531343539616138316433353830356566396130353436
                               3562643163366231316662386565383735653432386435610a306664636137376132643732393835

test/units/parsing/yaml/test_loader.py

@@ -204,7 +204,7 @@ class TestAnsibleLoaderVault(unittest.TestCase, YamlTestUtils):
             lines2.append('        %s' % line)
 
         vaulted_var = '\n'.join(lines2)
-        tagged_vaulted_var = u"""!vault-encrypted |\n%s""" % vaulted_var
+        tagged_vaulted_var = u"""!vault |\n%s""" % vaulted_var
         return tagged_vaulted_var
 
     def _build_stream(self, yaml_text):