From 32c2aae258e6772cd6f4d7279a0361bf2a998aac Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 11 May 2018 15:09:53 -0400 Subject: [PATCH] document lookup errors optoin (#39645) * document lookup errors optoin * changed to doc * updated as per feedback --- docs/docsite/rst/plugins/lookup.rst | 40 +++++++++++++++++++ .../rst/porting_guides/porting_guide_2.5.rst | 7 ++++ 2 files changed, 47 insertions(+) diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst index 240a6bc9c03..19cdec05478 100644 --- a/docs/docsite/rst/plugins/lookup.rst +++ b/docs/docsite/rst/plugins/lookup.rst @@ -65,6 +65,46 @@ You can combine lookups with :ref:`playbooks_filters`, :ref:`playbooks_tests` an - "{{lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list)}}" - ['a', 'c', 'd', 'c'] +.. versionadded:: 2.5 + +You can now 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. For example: + +To ignore errors:: + + - name: file doesnt exist, but i dont care .. file plugin itself warns anyways ... + debug: msg="{{ lookup('file', '/idontexist', errors='ignore') }}" + + [WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths) + + ok: [localhost] => { + "msg": "" + } + + +To get a warning instead of a failure:: + + - name: file doesnt exist, let me know, but continue + debug: msg="{{ lookup('file', '/idontexist', errors='warn') }}" + + [WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths) + + [WARNING]: An unhandled exception occurred while running the lookup plugin 'file'. Error was a , original message: could not locate file in lookup: /idontexist + + ok: [localhost] => { + "msg": "" + } + + +Fatal error (the default):: + + - name: file doesnt exist, FAIL (this is the default) + debug: msg="{{ lookup('file', '/idontexist', errors='strict') }}" + + [WARNING]: Unable to find '/idontexist' 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 , original message: could not locate file in lookup: /idontexist"} + + .. _query: query diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst index 1f07c7e954d..2a2c8ae2b7a 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -75,6 +75,7 @@ Included file: The relevant change in those examples is, that in Ansible 2.5, the included file defines the tag ``distro_include`` again. The tag is not inherited automatically. + Deprecated ========== @@ -219,6 +220,12 @@ Filter The lookup plugin API now throws an error if a non-iterable value is returned from a plugin. Previously, numbers or other non-iterable types returned by a plugin were accepted without error or warning. This change was made because plugins should always return a list. Please note that plugins that return strings and other non-list iterable values will not throw an error, but may cause unpredictable behavior. If you have a custom lookup plugin that does not return a list, you should modify it to wrap the return values in a list. +Lookup +------- + +A new option was added to lookup plugins globally named ``error`` which allows you to control how errors produced by the lookup are handled, before this option they were always fatal. Valid values for this option are ``warn``, ``ignore`` and ``strict``. See the :doc:`lookup <../plugins/lookup>` page for more details. + + Porting custom scripts ======================