Skip to content
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

Clarify the Vault guide and add Vault ID examples #55111

Merged
merged 8 commits into from Apr 23, 2019

Conversation

Projects
None yet
5 participants
@tacatac
Copy link
Contributor

commented Apr 10, 2019

SUMMARY

Add to the excellent work done in #43993.
In particular:

  • refer to file and variable-level encryption explicitly
  • show the general form for --vault-id usage
  • add vault id examples to the standard ansible-vault operations sections
ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

docs/docsite/rst/user_guide/vault.rst

ADDITIONAL INFORMATION

As far as I can tell, encrypt_string can really only be functionally used with variables, hence the "variable-level encryption" heading.

In general I think what makes Vault hard to understand is that there are actually two modes of operation now: "single" Vault and Vault ID, and they can both be used together.
I thought about splitting the guide into two parts but in the end I suppose adding examples side by side is the less disruptive approach.

tacatac added some commits Apr 6, 2019

Add reference to single variable vault encryption
* rST ref to jump to the section
Clarify the two targets of vault encryption
docs/docsite/rst/user_guide/vault.rst

* make the two possible target types for vault encryption in the "What
Can Be Encrypted With Vault" section clearer (that section currently has
many examples of file-level encryption but just one mention of variable
encryption)

* add notes about their possible advantages and drawbacks
Add the default form for --vault-id
Although Vault IDs are mentionned early on, the first usage example we
see is seven sections later in the "encrypt_string" section which is before
the "Labelling Vaults" section which actually explains how to use them.

The is commits adds the default usage form for the --vault-id option in the
"Vault ID and Multiple Vault Passwords" section which is the first section
where Vault IDs are mentionned.
Add Vault ID examples for normal operations
While Vault IDs are mentionned early on, the standard ansible-vault
operations shown (creating, editing, rekeying, etc.) have no
corresponding Vault ID examples.

The later Vault ID examples are all about ansible-playbook decryption
(bar one for encrypt_string).

Examples added here are for ansible-vault:
* create
* edit
* rekey
* encrypt
@ansibot

This comment has been minimized.

Copy link
Contributor

commented Apr 10, 2019

@ansibot ansibot removed the needs_triage label Apr 11, 2019

@maxwell-k
Copy link
Contributor

left a comment

I really like this PR. If anything it could be bolder in what it changes. After a short discussion in #ansible-docs on IRC we generally agree that less detail about the different versions and more focus on a "fresh" user new to vault, starting out with this current version would be great.

I made a few minor suggestions but overall I like this PR.

Show resolved Hide resolved docs/docsite/rst/user_guide/vault.rst Outdated
Show resolved Hide resolved docs/docsite/rst/user_guide/vault.rst Outdated
Show resolved Hide resolved docs/docsite/rst/user_guide/vault.rst Outdated
Show resolved Hide resolved docs/docsite/rst/user_guide/vault.rst

@ansibot ansibot added needs_revision and removed core_review labels Apr 16, 2019

@acozine

This comment has been minimized.

Copy link
Contributor

commented Apr 18, 2019

@tacatac thanks for contributing your vault expertise back to the documentation, and sharing your knowledge with the entire community. Can you take a look at the suggestions and comments above? I'd love to merge this in before the 2.8 release. Thanks!

maxwell-k and others added some commits Apr 18, 2019

Update docs/docsite/rst/user_guide/vault.rst
Co-Authored-By: tacatac <taca@kadisius.eu>
Update docs/docsite/rst/user_guide/vault.rst
Co-Authored-By: tacatac <taca@kadisius.eu>
Update docs/docsite/rst/user_guide/vault.rst
Co-Authored-By: tacatac <taca@kadisius.eu>

@ansibot ansibot added core_review and removed needs_revision labels Apr 21, 2019

@acozine

This comment has been minimized.

Copy link
Contributor

commented Apr 23, 2019

Thanks @tacatac @maxwell-k and @gundalow - this is a definite improvement.

@acozine acozine merged commit 79198ca into ansible:devel Apr 23, 2019

1 check passed

Shippable Run 119887 status is SUCCESS.
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.