From 8746d9ef87a9524c3c6d1640d5953aa1f2ae1285 Mon Sep 17 00:00:00 2001 From: Sam Doran Date: Fri, 25 May 2018 13:49:33 -0400 Subject: [PATCH] Add guidelines on developing lookup plugins (#38681) --- docs/docsite/rst/dev_guide/developing_plugins.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index e529316f4e..efb0e5869d 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -199,7 +199,11 @@ For examples on how to implement an inventory plug in, see the source code here: Lookup Plugins -------------- -Lookup plugins are used to pull in data from external data stores. Lookup plugins can be used within playbooks for both looping --- playbook language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins --- and to return values into a variable or parameter. +Lookup plugins are used to pull in data from external data stores. Lookup plugins can be used within playbooks both for looping --- playbook language constructs like ``with_fileglob`` and ``with_items`` are implemented via lookup plugins --- and to return values into a variable or parameter. + +Lookup plugins are very flexible, allowing you to retrieve and return any type of data. When writing lookup plugins, always return data of a consistent type that can be easily consumed in a playbook. Avoid parameters that change the returned data type. If there is a need to return a single value sometimes and a complex dictionary other times, write two different lookup plugins. + +Ansible includes many :ref:`filters ` which can be used to manipulate the data returned by a lookup plugin. Sometimes it makes sense to do the filtering inside the lookup plugin, other times it is better to return results that can be filtered in the playbook. Keep in mind how the data will be referenced when determing the appropriate level of filtering to be done inside the lookup plugin. Here's a simple lookup plugin implementation --- this lookup returns the contents of a text file as a variable: @@ -275,7 +279,8 @@ The following is an example of how this lookup is called:: tasks: - - debug: msg="the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }}" + - debug: + msg: the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }} For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup `_.