mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
252 lines
7.7 KiB
ReStructuredText
252 lines
7.7 KiB
ReStructuredText
.. _common_return_values:
|
|
|
|
Return Values
|
|
-------------
|
|
|
|
.. contents:: Topics
|
|
|
|
Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by
|
|
the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and on the :ref:`main docsite<ansible_documentation>`).
|
|
|
|
This document covers return values common to all modules.
|
|
|
|
.. note:: Some of these keys might be set by Ansible itself once it processes the module's return information.
|
|
|
|
|
|
Common
|
|
^^^^^^
|
|
|
|
backup_file
|
|
```````````
|
|
For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created.
|
|
|
|
.. code-block:: console
|
|
|
|
"backup_file": "./foo.txt.32729.2020-07-30@06:24:19~"
|
|
|
|
|
|
changed
|
|
```````
|
|
A boolean indicating if the task had to make changes to the target or delegated host.
|
|
|
|
.. code-block:: console
|
|
|
|
"changed": true
|
|
|
|
diff
|
|
````
|
|
Information on differences between the previous and current state. Often a dictionary with entries ``before`` and ``after``, which will then be formatted by the callback plugin to a diff view.
|
|
|
|
.. code-block:: console
|
|
|
|
"diff": [
|
|
{
|
|
"after": "",
|
|
"after_header": "foo.txt (content)",
|
|
"before": "",
|
|
"before_header": "foo.txt (content)"
|
|
},
|
|
{
|
|
"after_header": "foo.txt (file attributes)",
|
|
"before_header": "foo.txt (file attributes)"
|
|
}
|
|
|
|
failed
|
|
``````
|
|
A boolean that indicates if the task was failed or not.
|
|
|
|
.. code-block:: console
|
|
|
|
"failed": false
|
|
|
|
invocation
|
|
``````````
|
|
Information on how the module was invoked.
|
|
|
|
.. code-block:: console
|
|
|
|
"invocation": {
|
|
"module_args": {
|
|
"_original_basename": "foo.txt",
|
|
"attributes": null,
|
|
"backup": true,
|
|
"checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
|
|
"content": null,
|
|
"delimiter": null,
|
|
"dest": "./foo.txt",
|
|
"directory_mode": null,
|
|
"follow": false,
|
|
"force": true,
|
|
"group": null,
|
|
"local_follow": null,
|
|
"mode": "666",
|
|
"owner": null,
|
|
"regexp": null,
|
|
"remote_src": null,
|
|
"selevel": null,
|
|
"serole": null,
|
|
"setype": null,
|
|
"seuser": null,
|
|
"src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source",
|
|
"unsafe_writes": null,
|
|
"validate": null
|
|
}
|
|
|
|
msg
|
|
```
|
|
A string with a generic message relayed to the user.
|
|
|
|
.. code-block:: console
|
|
|
|
"msg": "line added"
|
|
|
|
rc
|
|
``
|
|
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains 'return code' of these utilities.
|
|
|
|
.. code-block:: console
|
|
|
|
"rc": 257
|
|
|
|
results
|
|
```````
|
|
If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module 'result' per item.
|
|
|
|
.. code-block:: console
|
|
|
|
"results": [
|
|
{
|
|
"ansible_loop_var": "item",
|
|
"backup": "foo.txt.83170.2020-07-30@07:03:05~",
|
|
"changed": true,
|
|
"diff": [
|
|
{
|
|
"after": "",
|
|
"after_header": "foo.txt (content)",
|
|
"before": "",
|
|
"before_header": "foo.txt (content)"
|
|
},
|
|
{
|
|
"after_header": "foo.txt (file attributes)",
|
|
"before_header": "foo.txt (file attributes)"
|
|
}
|
|
],
|
|
"failed": false,
|
|
"invocation": {
|
|
"module_args": {
|
|
"attributes": null,
|
|
"backrefs": false,
|
|
"backup": true
|
|
}
|
|
},
|
|
"item": "foo",
|
|
"msg": "line added"
|
|
},
|
|
{
|
|
"ansible_loop_var": "item",
|
|
"backup": "foo.txt.83187.2020-07-30@07:03:05~",
|
|
"changed": true,
|
|
"diff": [
|
|
{
|
|
"after": "",
|
|
"after_header": "foo.txt (content)",
|
|
"before": "",
|
|
"before_header": "foo.txt (content)"
|
|
},
|
|
{
|
|
"after_header": "foo.txt (file attributes)",
|
|
"before_header": "foo.txt (file attributes)"
|
|
}
|
|
],
|
|
"failed": false,
|
|
"invocation": {
|
|
"module_args": {
|
|
"attributes": null,
|
|
"backrefs": false,
|
|
"backup": true
|
|
}
|
|
},
|
|
"item": "bar",
|
|
"msg": "line added"
|
|
}
|
|
]
|
|
|
|
skipped
|
|
```````
|
|
A boolean that indicates if the task was skipped or not
|
|
|
|
.. code-block:: console
|
|
|
|
"skipped": true
|
|
|
|
stderr
|
|
``````
|
|
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities.
|
|
|
|
.. code-block:: console
|
|
|
|
"stderr": "ls: foo: No such file or directory"
|
|
|
|
stderr_lines
|
|
````````````
|
|
When `stderr` is returned we also always provide this field which is a list of strings, one item per line from the original.
|
|
|
|
.. code-block:: console
|
|
|
|
"stderr_lines": [
|
|
"ls: doesntexist: No such file or directory"
|
|
]
|
|
|
|
stdout
|
|
``````
|
|
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities.
|
|
|
|
.. code-block:: console
|
|
|
|
"stdout": "foo!"
|
|
|
|
stdout_lines
|
|
````````````
|
|
When `stdout` is returned, Ansible always provides a list of strings, each containing one item per line from the original output.
|
|
|
|
.. code-block:: console
|
|
|
|
"stdout_lines": [
|
|
"foo!"
|
|
]
|
|
|
|
|
|
.. _internal_return_values:
|
|
|
|
Internal use
|
|
^^^^^^^^^^^^
|
|
|
|
These keys can be added by modules but will be removed from registered variables; they are 'consumed' by Ansible itself.
|
|
|
|
ansible_facts
|
|
`````````````
|
|
This key should contain a dictionary which will be appended to the facts assigned to the host. These will be directly accessible and don't require using a registered variable.
|
|
|
|
exception
|
|
`````````
|
|
This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv).
|
|
|
|
warnings
|
|
````````
|
|
This key contains a list of strings that will be presented to the user.
|
|
|
|
deprecations
|
|
````````````
|
|
This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are `msg` and `version`, values are string, value for the `version` key can be an empty string.
|
|
|
|
.. seealso::
|
|
|
|
:ref:`list_of_collections`
|
|
Browse existing collections, modules, and plugins
|
|
`GitHub modules directory <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_
|
|
Browse source of core and extras modules
|
|
`Mailing List <https://groups.google.com/group/ansible-devel>`_
|
|
Development mailing list
|
|
:ref:`communication_irc`
|
|
How to join Ansible chat channels
|