From a2c38c47aa764130af93c2810f8e4cee50ceb05d Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 3 Feb 2017 15:28:50 -0500 Subject: [PATCH] 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 | 1 + docs/docsite/rst/playbooks_vault.rst | 24 +++++++++++++++++++ lib/ansible/parsing/yaml/constructor.py | 4 +--- lib/ansible/parsing/yaml/dumper.py | 2 +- lib/ansible/parsing/yaml/objects.py | 2 +- .../roles/test_vault_embedded/vars/main.yml | 4 ++-- test/units/parsing/yaml/test_loader.py | 2 +- 7 files changed, 31 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7a6e8f5c0a..ab7855103ef 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/docsite/rst/playbooks_vault.rst b/docs/docsite/rst/playbooks_vault.rst index 04a50ddd95c..c2e561e43b2 100644 --- a/docs/docsite/rst/playbooks_vault.rst +++ b/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 diff --git a/lib/ansible/parsing/yaml/constructor.py b/lib/ansible/parsing/yaml/constructor.py index 0a53fb1c7ff..be2c3c193b4 100644 --- a/lib/ansible/parsing/yaml/constructor.py +++ b/lib/ansible/parsing/yaml/constructor.py @@ -156,6 +156,4 @@ AnsibleConstructor.add_constructor( u'!unsafe', AnsibleConstructor.construct_yaml_unsafe) -AnsibleConstructor.add_constructor( - u'!vault-encrypted', - AnsibleConstructor.construct_vault_encrypted_unicode) +AnsibleConstructor.add_constructor(u'!vault', AnsibleConstructor.construct_vault_encrypted_unicode) diff --git a/lib/ansible/parsing/yaml/dumper.py b/lib/ansible/parsing/yaml/dumper.py index 58c2fb73ba2..f04c3200f2e 100644 --- a/lib/ansible/parsing/yaml/dumper.py +++ b/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 diff --git a/lib/ansible/parsing/yaml/objects.py b/lib/ansible/parsing/yaml/objects.py index 23a5547f7e8..67aa2b99675 100644 --- a/lib/ansible/parsing/yaml/objects.py +++ b/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): diff --git a/test/integration/targets/vault/roles/test_vault_embedded/vars/main.yml b/test/integration/targets/vault/roles/test_vault_embedded/vars/main.yml index e9c568eac10..54e6004f437 100644 --- a/test/integration/targets/vault/roles/test_vault_embedded/vars/main.yml +++ b/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 diff --git a/test/units/parsing/yaml/test_loader.py b/test/units/parsing/yaml/test_loader.py index 7c09437b728..46a554379db 100644 --- a/test/units/parsing/yaml/test_loader.py +++ b/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):