cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

document lookup errors optoin (#39645)

Browse source 
* document lookup errors optoin

* changed to doc

* updated as per feedback
This commit is contained in:
Brian Coca 2018-05-11 15:09:53 -04:00 committed by GitHub
parent 00a6b19e58
commit 32c2aae258
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 47 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
docs/docsite/rst/plugins/lookup.rst
View file

@ -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 <class 'ansible.errors.AnsibleError'>, 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 <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /idontexist"}
.. _query:
query

7
docs/docsite/rst/porting_guides/porting_guide_2.5.rst
View file

@ -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
======================