Skip to content

Commit

Permalink
Link to templating functions from the variables page (#2258)
Browse files Browse the repository at this point in the history
* Link to templating functions from the variables page

Add query/q templating function to the working with playbooks page

* fix typos, simplify example

(cherry picked from commit 2b7145d)
  • Loading branch information
s-hertel authored and patchback[bot] committed Dec 10, 2024
1 parent 3f81382 commit 7185731
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 3 deletions.
30 changes: 27 additions & 3 deletions docs/docsite/rst/playbook_guide/playbooks_lookups.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ Lookup plugins retrieve data from outside sources such as files, databases, key/

.. _lookups_and_variables:

Using lookups in variables
==========================
The lookup function
===================

You can populate variables using lookups. Ansible evaluates the value each time it is executed in a task (or template).
You can use the ``lookup`` function to populate variables dynamically. Ansible evaluates the value each time it is executed in a task (or template).

.. code-block:: yaml+jinja

Expand All @@ -21,6 +21,30 @@ You can populate variables using lookups. Ansible evaluates the value each time
- debug:
msg: "motd value is {{ motd_value }}"

The first argument to the ``lookup`` function is required and specifies the name of the lookup plugin. If the lookup plugin is in a collection, the fully qualified name must be provided, since the :ref:`collections keyword<collections_keyword>` does not apply to lookup plugins.

The ``lookup`` function also accepts an optional boolean keyword ``wantlist``, which defaults to ``False``. When ``True``, the result of the lookup is ensured to be a list.

Refer to the lookup plugin's documentation to see plugin-specific arguments and keywords.

.. _lookups_and_variables_query:

The query/q function
====================

This function is shorthand for ``lookup(..., wantlist=True)``. These are equivalent:

.. code-block:: yaml+jinja

block:
- debug:
msg: "{{ item }}"
loop: "{{ lookup('ns.col.lookup_items', wantlist=True) }}"

- debug:
msg: "{{ item }}"
loop: "{{ q('ns.col.lookup_items') }}"

For more details and a list of lookup plugins in ansible-core, see :ref:`plugins_lookup`. You may also find lookup plugins in collections. You can review a list of lookup plugins installed on your control machine with the command ``ansible-doc -l -t lookup``.

.. seealso::
Expand Down
4 changes: 4 additions & 0 deletions docs/docsite/rst/playbook_guide/playbooks_variables.rst
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ This table gives examples of valid and invalid variable names:

.. _Python keywords: https://docs.python.org/3/reference/lexical_analysis.html#keywords

.. note:: Certain :ref:`variables<special_variables>` are defined internally, and cannot be defined by the user.

.. note:: You may want to avoid variable names that would overwrite Jinja2 global functions listed in :ref:`working_with_playbooks`, such as :ref:`lookup<lookups_and_variables>`, :ref:`query<lookups_and_variables_query>`, :ref:`q<lookups_and_variables_query>`, :ref:`now<templating_now>`, and :ref:`undef<templating_undef>`.

Simple variables
================

Expand Down

0 comments on commit 7185731

Please sign in to comment.