Toshio Kuratomi 9dda393d70

* Build documentation for Ansible-2.10 (formerly known as ACD).

Builds plugin docs from collections whose source is on galaxy

The new command downloads collections from galaxy, then finds the
plugins inside of them to get the documentation for those plugins.

* Update the python syntax checks
  * docs builds can now require python 3.6+.

* Move plugin formatter code out to an external tool, antsibull-docs.
  Collection owners want to be able to extract docs for their own
  websites as well.
* The jinja2 filters, tests, and other support code have moved to antsibull
* Remove document_plugins as that has now been integrated into antsibull-docs

* Cleanup and bugfix to other build script code:
  * The Commands class needed to have its metaclass set for abstractmethod
    to work correctly
  * Fix lint issues in some command plugins

* Add the docs/docsite/rst/collections to .gitignore as
  everything in that directory will be generated so we don't want any of
  it saved in the git repository
* gitignore the build dir and remove edit docs link on module pages

* Add docs/rst/collections as a directory to remove on make clean
* Split the collections docs from the main docs

* remove version and edit on github
* remove version banner for just collections
* clarify examples need collection keyword defined

* Remove references to plugin documentation locations that no longer exist.
  * Perhaps the pages in plugins/*.rst should be deprecated
    altogether and their content moved?
  * If not, perhaps we want to rephrase and link into the collection
    documentation?
  * Or perhaps we want to link to the plugins which are present in
    collections/ansible/builtin?

* Remove PYTHONPATH from the build-ansible calls
  One of the design goals of the build-ansible.py script was for it to
  automatically set its library path to include the checkout of ansible
  and the library of code to implement itself.  Because it automatically
  includes the checkout of ansible, we don't need to set PYTHONPATH in
  the Makefile any longer.

* Create a command to only build ansible-base plugin docs
  * When building docs for devel, only build the ansible-base docs for
    now.  This is because antsibull needs support for building a "devel
    tree" of docs.  This can be changed once that is implemented
  * When building docs for the sanity tests, only build the ansible-base
    plugin docs for now.  Those are the docs which are in this repo so
    that seems appropriate for now.

2020-07-17 13:07:35 -07:00

6.2 KiB

Raw Blame History

Lookup Plugins

Lookup plugins are an Ansible-specific extension to the Jinja2 templating language. You can use lookup plugins to access data from outside sources (files, databases, key/value stores, APIs, and other services) within your playbooks. Like all templating <playbooks_templating>, lookups execute and are evaluated on the Ansible control machine. Ansible makes the data returned by a lookup plugin available using the standard templating system. You can use lookup plugins to load variables or templates with information from external sources.

Note

- Lookups are executed with a working directory relative to the role or play, as opposed to local tasks, which are executed relative the executed script. - Pass wantlist=True to lookups to use in Jinja2 template "for" loops.

Warning

- Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the |quote filter to ensure safe usage.

Enabling lookup plugins

Ansible enables all lookup plugins it can find. You can activate a custom lookup by either dropping it into a lookup_plugins directory adjacent to your play, inside the plugins/lookup/ directory of a collection you have installed, inside a standalone role, or in one of the lookup directory sources configured in ansible.cfg <ansible_configuration_settings>.

Using lookup plugins

You can use lookup plugins anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the template <template_module> module.

vars:
  file_contents: "{{lookup('file', 'path/to/file.txt')}}"

Lookups are an integral part of loops. Wherever you see with_, the part after the underscore is the name of a lookup. For this reason, most lookups output lists and take lists as input; for example, with_items uses the items <items_lookup> lookup:

tasks:
  - name: count to 3
    debug: msg={{item}}
    with_items: [1, 2, 3]

You can combine lookups with filters <playbooks_filters>, tests <playbooks_tests> and even each other to do some complex data generation and manipulation. For example:

tasks:
  - name: valid but useless and over complicated chained lookups and filters
    debug: msg="find the answer here:\n{{ lookup('url', 'https://google.com/search/?q=' + item|urlencode)|join(' ') }}"
    with_nested:
      - "{{lookup('consul_kv', 'bcs/' + lookup('file', '/the/question') + ', host=localhost, port=2000')|shuffle}}"
      - "{{lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list)}}"
      - ['a', 'c', 'd', 'c']

2.6

You can control how errors behave in all lookup plugins by setting errors to ignore, warn, or strict. The default setting is strict, which causes the task to fail if the lookup returns an error. For example:

To ignore lookup errors:

- name: if this file does not exist, I do not care .. file plugin itself warns anyway ...
  debug: msg="{{ lookup('file', '/nosuchfile', errors='ignore') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

ok: [localhost] => {
    "msg": ""
}

To get a warning instead of a failure:

- name: if this file does not exist, let me know, but continue
  debug: msg="{{ lookup('file', '/nosuchfile', errors='warn') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

[WARNING]: An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /nosuchfile

ok: [localhost] => {
    "msg": ""
}

To get a fatal error (the default):

- name: if this file does not exist, FAIL (this is the default)
  debug: msg="{{ lookup('file', '/nosuchfile', errors='strict') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

fatal: [localhost]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /nosuchfile"}

Forcing lookups to return lists: `query` and `wantlist=True`

2.5

In Ansible 2.5, a new Jinja2 function called query was added for invoking lookup plugins. The difference between lookup and query is largely that query will always return a list. The default behavior of lookup is to return a string of comma separated values. lookup can be explicitly configured to return a list using wantlist=True.

This feature provides an easier and more consistent interface for interacting with the new loop keyword, while maintaining backwards compatibility with other uses of lookup.

The following examples are equivalent:

lookup('dict', dict_variable, wantlist=True)

query('dict', dict_variable)

As demonstrated above, the behavior of wantlist=True is implicit when using query.

Additionally, q was introduced as a shortform of query:

q('dict', dict_variable)

Plugin list

You can use ansible-doc -t lookup -l to see the list of available plugins. Use ansible-doc -t lookup <plugin name> to see specific documents and examples.

about_playbooks: An introduction to playbooks
inventory_plugins: Ansible inventory plugins
callback_plugins: Ansible callback plugins
playbooks_filters: Jinja2 filter plugins
playbooks_tests: Jinja2 test plugins
playbooks_lookups: Jinja2 lookup plugins
User Mailing List: Have a question? Stop by the google group!
irc.freenode.net: #ansible IRC chat channel

6.2 KiB Raw Blame History