New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update vault docs for client scripts, multiple keys and misc #43993

Open
wants to merge 10 commits into
base: devel
from

Conversation

Projects
None yet
5 participants
@orthanc
Contributor

orthanc commented Aug 11, 2018

SUMMARY

Update the ansiblle-vault docs to explain the special handling of -client scripts which are passed the vault id.

Also update the ansible-playbook docs of vault to prefer --vault-id and indicate that multiple keys are suported.

The switch to vault-id is based on the main ansibe-vault docs indcating that's the preferred option. I'd particularly like confirmation that this is preferred as personally I'd argue in favour of preferring ask-vault-pass/vault-password-file over vault-id when only a single key is in use since the vault-id syntax is confusing when the vault is not named.

Fixes #43991

ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

ansible-vault

ANSIBLE VERSION
ansible 2.7.0.dev0 (update_vault_docs_for_client_scripts 690f1d52ae) last updated 2018/08/11 17:32:08 (GMT +1300)
  config file = None
  configured module search path = [u'USER_HOME/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = ANSIBLE_HOME/lib/ansible
  executable location = ANSIBLE_HOME/bin/ansible
  python version = 2.7.15rc1 (default, Apr 15 2018, 21:51:34) [GCC 7.3.0]
@ansibot

This comment has been minimized.

Contributor

ansibot commented Aug 11, 2018

@orthanc orthanc force-pushed the orthanc:update_vault_docs_for_client_scripts branch Aug 11, 2018

@orthanc orthanc changed the title from WIP: Update vault docs for client scripts, multiple keys and misc to Update vault docs for client scripts, multiple keys and misc Aug 11, 2018

@orthanc

This comment has been minimized.

Contributor

orthanc commented Aug 11, 2018

ready_for_review

@ansibot ansibot removed the WIP label Aug 11, 2018

@orthanc orthanc force-pushed the orthanc:update_vault_docs_for_client_scripts branch Aug 11, 2018

docs/docsite/rst/user_guide/playbooks_vault.rst Outdated
.. note::
The :option:`--vault-id <ansible-playbook --vault-id>` flag is only avalibe in Ansible 2.4 or later.
Prior to Ansible 2.4, flags :option:`--ask-vault-pass <ansible-vault --ask-vault-pass>` or
:option:`--vault-password-file <ansible-vault --vault-password-file>` are used.

This comment has been minimized.

@bcoca

bcoca Aug 13, 2018

Member

these are still usable if you dont want to use the 'id' system, i would leave them in the main text and maybe clarify this in the notes

docs/docsite/rst/user_guide/playbooks_vault.rst Outdated
The :option:`--vault-id <ansible-pull --vault-id>` 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.
*Prior to Ansible 2.4*

This comment has been minimized.

@bcoca

bcoca Aug 13, 2018

Member

the same here, this is in 'addition' as the old 'single vault options' still work

@bcoca bcoca removed the needs_triage label Aug 13, 2018

@bcoca bcoca requested review from alikins and acozine Aug 13, 2018

@bcoca

Just don't imply that the 'single vault' options don't/won't work after 2.4, it should be clear for those using a single vault that they continue to work.

@orthanc

This comment has been minimized.

Contributor

orthanc commented Aug 13, 2018

Thanks,

I'm trying to work out the status of the single vault options to make sure the tone and guidance is consistent between the two pieces of documentation. Are they:

  1. Preferable when there is only a single vault in use for both ansible-playbook and ansible-vault
  2. Preferable for ansible-playbook when there is only a single vault in use but discouraged for ansible-vault where it's preferable to identify the vault being encrypted
  3. Fully supported but discouraged as preference is to standardize on vault-id

I gathered from the vault documentation that the state was 3, but If I've miss-understood that I'll update both docs to reflect the state.

If the state is 3 I'll just update the doc to be clearer that they still work but are discouraged.

Tidy up of use of vault-id vs ask-vault-pass options in vault docs.
Use ask-vault-pass / vault-password-file whenever dealing with a single
unlabeled vault.

Introduce the concept of labeling a vault for clarity even if only a
single password is in use for a given run.

Rework multi-password section to align to these concepts.

@orthanc orthanc force-pushed the orthanc:update_vault_docs_for_client_scripts branch Aug 18, 2018

@orthanc orthanc force-pushed the orthanc:update_vault_docs_for_client_scripts branch to 501e051 Aug 18, 2018

@orthanc

This comment has been minimized.

Contributor

orthanc commented Aug 18, 2018

ready_for_review

Based on discussion in the IRC chat it seems --ask-vault-pass and --vault-password-file are preferrable when there's only a single password in use.

So latest commits rework both the vault and playbookkk documentation to be consistent that:

  • ask-vault-pass and vault-password-file are preferrable when there is only a single password in use
  • labeled vault-id is a valid option for where there are multiple passwords in use in the inventory but only one used in a given run
  • labeled vault-id must be used when multiple passwords are needed for a single run
  • unlabeled vault-id is valid, but rarely used (preferring ask-vault-pass or vault-password-file)

Then add the documentation of the client scripts in the context of that.

To make this read better I've moved the Vault Ids and Multiple Vault Password section of the vault docs to the top with the rest of the concepts so vault id's are introduced early before the examples of using them.

@ansibot ansibot removed the needs_revision label Aug 18, 2018

@dglinder

This comment has been minimized.

Contributor

dglinder commented Aug 20, 2018

Thanks for the documentation update, @orthanc, around using multiple --vault-id entries on the ansible-playbook command, but I don't see anything covering how to create a variable with multiple versions using different --vault-id? Can you add some commentary around creating this using the ansible-vault encrypt options?

@acozine

I have not tested all the approaches described in this PR, but assuming that they are all correct, I'd say this PR is an improvement. Take care of the typos and it gets a thumbs-up from me.

Show resolved Hide resolved docs/docsite/rst/user_guide/playbooks_vault.rst Outdated
Show resolved Hide resolved docs/docsite/rst/user_guide/playbooks_vault.rst Outdated
Remove explicit Notes about lack of vault-id support before 2.4
Since prior to 2.4 is no longer supported these are redundant.

Also fix a typo.
@orthanc

This comment has been minimized.

Contributor

orthanc commented Aug 21, 2018

ready_for_review

I've fixed the typos and removed the two explicit note boxes about support being added in 2.4.

There are a number of other references to 2.3, 2.4 or even 2.1 remaining in these two files, but replacing all of those requires a bit more re-writing so I'd prefer to do that in a subsequent PR.

Similarly I think @dglinder 's suggestion of clarifying creation of multiple vaults would also be better in a subequent PR as it will likely open a best practice / preference discussion. There's pretty resonable overap with the sections that need version number's removed so I'll likely tackle both of these as one PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment