docs - lookup guide #211
docs - lookup guide #211
Conversation
This comment was marked as outdated.
This comment was marked as outdated.
docs/docsite/rst/lookup_guide.rst
Outdated
|
|
||
| So the third thing the lookup does is assume that you're probably trying to read a ``kv`` secret, and to then try to infer if the response is from ``kv2``, because the responses from version 2 include metadata and have the secret value additionally wrappped in another structure. In that way, it seeks to make the response from version 2 look more like the response from version 1. | ||
|
|
||
| Since the ``kv`` store has one or more key/value pairs in each secret, the lookup also supports a non-standard suffix in its path that can be used to access a value belonging to one specific key, via the ``:keyname`` syntax. While this is useful to provide a compact way to access a single secret value (admittedly a very common use case), it complicates the implementation and leads to bad habits. |
There was a problem hiding this comment.
I'd probably add a header here. Something like Finding specific values with ':keyname'. Then lay out the pros and cons of this functionality.
There was a problem hiding this comment.
Maybe it would be better just to shorten it, I don't want to call too much attention to it since we're not looking to promote use of it, it was meant as historical context basically. Will think about it a bit.
| Writes in Vault | ||
| --------------- | ||
|
|
||
| Operations that perform writes in Vault are not limited to the obvious ones such as writing a secret value, creating a policy, or enabling a new auth method. |
There was a problem hiding this comment.
Is this section more about Vault generally, or about hashi_vault lookup operations specifically?
There was a problem hiding this comment.
This section is about Vault generally, and then relating those things to the lookups in this collection (not just the hashi_vault lookup).
| How to reason about when to use lookups | ||
| --------------------------------------- | ||
|
|
||
| Because there is potential for writes in any lookup, it is very important to carefully consider when you are using a lookup vs. a module/other plugin. Check mode has no effect on lookups, so there is potential to perform many writes within your check mode run, but maybe sometimes you want that, for example if you're performing a ``vault_login`` via lookup to retrieve a token to use in your module calls, you may want that to still happen in check mode so that your module calls can properly check the things they need to. |
There was a problem hiding this comment.
Ahhhh, I see what you mean by "check mode has no effect on lookups" - you mean, "even running in check mode, your lookup plugin is going to do whatever it would do on a real run, so be careful . . . " That is a very important point - I'd make it more explicit here and above.
There was a problem hiding this comment.
Yes exactly. I may move some of this stuff about writes and implicit writes into its own document at some point as well, because while it can be trickier with lookups, some of it applies to modules too.
For example: vault_login (the module) does not perform a login in check mode. vault_read (the module), takes all the same authentication parameters as vault_login, and will perform the login even in check mode, so that it can execute the read in check mode as well. The vault_token_create module (#213) similarly will perform the login with its authentication parameters, but will not create a token in check mode.
But for now I think I will like to keep some of this here, there's always room to reorganize and move things to new pages later.
Co-authored-by: Felix Fontein <felix@fontein.de>
briantist
force-pushed
the
docs/lookup_guide
branch
from
3ed5427
to
70dadd9
Compare
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Docs Build 📝Thank you for contribution!✨ This PR has been merged and the docs are now incorporated into |
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
|
@acozine thanks so much for your help on this, your suggestions so far have really improved it already! I merged today so that I could get this content into a release, but I'm happy to accept PRs to it, or if you have comments on the closed PR I will read them and make adjustments. Thanks again! |
SUMMARY
Adds a lookup guide to the docsite.
This discusses topics such as:
hashi_vaultlookup and its future in the collectionThis PR also includes the changes in ansible-community/antsibull#391 since we commit the output ofantsibull sphinx-initin the collection (so developers can build local docs more easily and so we can slightly customize the index page).^ these changes were moved to #215 .
ISSUE TYPE
COMPONENT NAME
docsite
ADDITIONAL INFORMATION
N/A