Standard method of passing extra arguments to lookup plugins

[abadger]

Proposal: Standard Method of Passing Extra Arguments to Lookup Plugins

Author: Toshio Kuratomi @abadger

Date: 2016/05/12

• Status: WIP
• Proposal type: Plugin API
• Targeted Release: <future release #, ex. 2.2>
• Associated PR: <link to GH PR in ansible/proposals if PR was submitted>
• Estimated time to implement: 3 days

Motivation

Describe the reasons for this proposal.

Problems

A couple bugs lead me to find that lookup modules have a variety of ways of specifying their parameters:

• lookup password does not deal well with spaces in the path ansible-modules-core#1968
• Can't pass token to Consul lookup plugin? ansible-modules-extras#857

Solution proposal

We need to add standard ways to specify and parse parameters to lookup plugins. We'd officially support something like the following (examples only. Exact syntax subject to change as it's thought through):

vars:
  pass: "{{ lookup( 'password', [{ term: "/dir with spaces/", length: 25, } ]) }}"
tasks:
  - debug:
    msg: "{{ item }}"
    with_password:
    - term: "/dir with spaces/"
      length: 25
  - debug:
    msg: "{{ item }}"
    with_password:
      - "/dir with spaces"

We would deprecate the former methods of specifying parameters:

- pass: "{{ lookup('password', '/dir_without_spaces length=25') }}"

I don't know if we'd continue to support the current style of arg passing that has support from the code when used via lookup() but not when used via with_* and that some plugins (for instance, password), are currently ignoring.

- pass: "{{ lookup('password', ["/dir with spaces"], length=25) }}"
# No when_password: style equivalent of the above.

Dependencies (optional)

Explain any dependencies. This section is optional but could be helpful.

• Dependency Docker Modules #1
• Dependency Adding Docker module proposals #2

Testing (optional)

Does / should this require testing, and if so, how? Describe here. This section is optional but could be helpful.

Documentation (optional)

Does / should this require documentation? If so, describe here. This section is optional but could be helpful.

Anything else?

If you'd like to add anything else beyond the above required and optional sections, you are welcome to do so.

[freeseacher]

any news on that ?
i am trying to understand how to pass host variable to consul_kv module. and have no idea :(

[abadger]

We need ideas of what this looks like and then ideas of how to implement the best of those ideas. This really just identifies the problem.

[bcoca]

+1 to "arguments are always a dictionary" and deprecate old 'stringified' methods.

[abadger]

Closing this as it's now resolved. We advise using loop: and explicitly using query() or lookup() to pass arguments into lookup plugins. Arguments passed this way should always be coded as key word arguments (positional arguments to lookup plugins end up as the list of terms).

[rgm3]

@abadger Could you please provide an example of your advice or submit one to the lookup plugin documentation?

[abadger]

Hey, we don't normally see additional comments on closed bugs but luckily I saw your message on IRC. Here's an example of how to code the plugin: https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/lookup/aws_ssm.py#L142
And that plugin's documentation has an example of using it with loop: and query: https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/lookup/aws_ssm.py#L96

Documentation in the lookup plugin docs would be good if someone wants to work on that....

[fkuep]

@abadger Thank You!
Also ther is now a comment on LookupBase:
https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/lookup/__init__.py#L78-L105

Your aws_ssm example has moved
The I have working links from an old commit-hash

• how to code the plugin
• the loop example in the documentation

[bcoca]

This is now 'implemented' via the plugin config system, all lookups should now shift to set_options call in their run method (see core lookups for examples)