"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/docsite/rst/dev_guide/developing_program_flow_modules.rst" between
ansible-2.14.0.tar.gz and ansible-2.14.1rc1.tar.gz

About: Ansible is an IT Configuration Management, Deployment & Orchestration tool.
Release candidate.

developing_program_flow_modules.rst  (ansible-2.14.0):developing_program_flow_modules.rst  (ansible-2.14.1rc1)
skipping to change at line 117 skipping to change at line 117
These modules typically parse the contents of ``json_arguments`` using a JSON These modules typically parse the contents of ``json_arguments`` using a JSON
library and then use them as native variables throughout the code. library and then use them as native variables throughout the code.
.. _flow_want_json_modules: .. _flow_want_json_modules:
Non-native want JSON modules Non-native want JSON modules
---------------------------- ----------------------------
If a module has the string ``WANT_JSON`` in it anywhere, Ansible treats If a module has the string ``WANT_JSON`` in it anywhere, Ansible treats
it as a non-native module that accepts a filename as its only command line it as a non-native module that accepts a filename as its only command-line
parameter. The filename is for a temporary file containing a :term:`JSON` parameter. The filename is for a temporary file containing a :term:`JSON`
string containing the module's parameters. The module needs to open the file, string containing the module's parameters. The module needs to open the file,
read and parse the parameters, operate on the data, and print its return data read and parse the parameters, operate on the data, and print its return data
as a JSON encoded dictionary to stdout before exiting. as a JSON encoded dictionary to stdout before exiting.
These types of modules are self-contained entities. As of Ansible 2.1, Ansible These types of modules are self-contained entities. As of Ansible 2.1, Ansible
only modifies them to change a shebang line if present. only modifies them to change a shebang line if present.
.. seealso:: Examples of Non-native modules written in ruby are in the `Ansible .. seealso:: Examples of Non-native modules written in ruby are in the `Ansible
for Rubyists <https://github.com/ansible/ansible-for-rubyists>`_ repository. for Rubyists <https://github.com/ansible/ansible-for-rubyists>`_ repository.
skipping to change at line 176 skipping to change at line 176
with several parameters to be passed to the module. Ansible takes these with several parameters to be passed to the module. Ansible takes these
values and processes them in various ways before they are finally executed on values and processes them in various ways before they are finally executed on
the remote machine. the remote machine.
.. _flow_executor_task_executor: .. _flow_executor_task_executor:
Executor/task_executor Executor/task_executor
---------------------- ----------------------
The TaskExecutor receives the module name and parameters that were parsed from The TaskExecutor receives the module name and parameters that were parsed from
the :term:`playbook <playbooks>` (or from the command line in the case of the :term:`playbook <playbooks>` (or from the command-line in the case of
:command:`/usr/bin/ansible`). It uses the name to decide whether it's looking :command:`/usr/bin/ansible`). It uses the name to decide whether it's looking
at a module or an :ref:`Action Plugin <flow_action_plugins>`. If it's at a module or an :ref:`Action Plugin <flow_action_plugins>`. If it's
a module, it loads the :ref:`Normal Action Plugin <flow_normal_action_plugin>` a module, it loads the :ref:`Normal Action Plugin <flow_normal_action_plugin>`
and passes the name, variables, and other information about the task and play and passes the name, variables, and other information about the task and play
to that Action Plugin for further processing. to that Action Plugin for further processing.
.. _flow_normal_action_plugin: .. _flow_normal_action_plugin:
The ``normal`` action plugin The ``normal`` action plugin
---------------------------- ----------------------------
skipping to change at line 282 skipping to change at line 282
:ref:`Ansiballz` framework the proper way is to instead instantiate an :ref:`Ansiballz` framework the proper way is to instead instantiate an
`AnsibleModule` and then access the version from `AnsibleModule` and then access the version from
:attr:``AnsibleModule.ansible_version``. :attr:``AnsibleModule.ansible_version``.
- :code:`"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>"` is substituted with - :code:`"<<INCLUDE_ANSIBLE_MODULE_COMPLEX_ARGS>>"` is substituted with
a string which is the Python ``repr`` of the :term:`JSON` encoded module a string which is the Python ``repr`` of the :term:`JSON` encoded module
parameters. Using ``repr`` on the JSON string makes it safe to embed in parameters. Using ``repr`` on the JSON string makes it safe to embed in
a Python file. In new-style Python modules under the Ansiballz framework a Python file. In new-style Python modules under the Ansiballz framework
this is better accessed by instantiating an `AnsibleModule` and this is better accessed by instantiating an `AnsibleModule` and
then using :attr:`AnsibleModule.params`. then using :attr:`AnsibleModule.params`.
- :code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is - :code:`<<SELINUX_SPECIAL_FILESYSTEMS>>` substitutes a string which is
a comma separated list of file systems which have a file system dependent a comma-separated list of file systems which have a file system dependent
security context in SELinux. In new-style Python modules, if you really security context in SELinux. In new-style Python modules, if you really
need this you should instantiate an `AnsibleModule` and then use need this you should instantiate an `AnsibleModule` and then use
:attr:`AnsibleModule._selinux_special_fs`. The variable has also changed :attr:`AnsibleModule._selinux_special_fs`. The variable has also changed
from a comma separated string of file system names to an actual python from a comma-separated string of file system names to an actual python
list of filesystem names. list of file system names.
- :code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` substitutes the module - :code:`<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>` substitutes the module
parameters as a JSON string. Care must be taken to properly quote the parameters as a JSON string. Care must be taken to properly quote the
string as JSON data may contain quotes. This pattern is not substituted string as JSON data may contain quotes. This pattern is not substituted
in new-style Python modules as they can get the module parameters another in new-style Python modules as they can get the module parameters another
way. way.
- The string :code:`syslog.LOG_USER` is replaced wherever it occurs with the - The string :code:`syslog.LOG_USER` is replaced wherever it occurs with the
``syslog_facility`` which was named in :file:`ansible.cfg` or any ``syslog_facility`` which was named in :file:`ansible.cfg` or any
``ansible_syslog_facility`` inventory variable that applies to this host. I n ``ansible_syslog_facility`` inventory variable that applies to this host. I n
new-style Python modules this has changed slightly. If you really need to new-style Python modules this has changed slightly. If you really need to
access it, you should instantiate an `AnsibleModule` and then use access it, you should instantiate an `AnsibleModule` and then use
skipping to change at line 325 skipping to change at line 325
extracts just the Ansible module script from the zip file and places that in extracts just the Ansible module script from the zip file and places that in
the temporary directory as well. Then it sets the PYTHONPATH to find Python the temporary directory as well. Then it sets the PYTHONPATH to find Python
modules inside of the zip file and imports the Ansible module as the special nam e, ``__main__``. modules inside of the zip file and imports the Ansible module as the special nam e, ``__main__``.
Importing it as ``__main__`` causes Python to think that it is executing a scrip t rather than simply Importing it as ``__main__`` causes Python to think that it is executing a scrip t rather than simply
importing a module. This lets Ansible run both the wrapper script and the module code in a single copy of Python on the remote machine. importing a module. This lets Ansible run both the wrapper script and the module code in a single copy of Python on the remote machine.
.. note:: .. note::
* Ansible wraps the zipfile in the Python script for two reasons: * Ansible wraps the zipfile in the Python script for two reasons:
* for compatibility with Python 2.6 which has a less * for compatibility with Python 2.6 which has a less
functional version of Python's ``-m`` command line switch. functional version of Python's ``-m`` command-line switch.
* so that pipelining will function properly. Pipelining needs to pipe th e * so that pipelining will function properly. Pipelining needs to pipe th e
Python module into the Python interpreter on the remote node. Python Python module into the Python interpreter on the remote node. Python
understands scripts on stdin but does not understand zip files. understands scripts on stdin but does not understand zip files.
* Prior to Ansible 2.7, the module was executed by a second Python interpret er instead of being * Prior to Ansible 2.7, the module was executed by a second Python interpret er instead of being
executed inside of the same process. This change was made once Python-2.4 support was dropped executed inside of the same process. This change was made once Python-2.4 support was dropped
to speed up module execution. to speed up module execution.
In Ansiballz, any imports of Python modules from the In Ansiballz, any imports of Python modules from the
skipping to change at line 379 skipping to change at line 379
.. note:: .. note::
Prior to Ansible 2.7, the Ansible module was invoked in a second Python inte rpreter and the Prior to Ansible 2.7, the Ansible module was invoked in a second Python inte rpreter and the
arguments were then passed to the script over the script's stdin. arguments were then passed to the script over the script's stdin.
.. _flow_internal_arguments: .. _flow_internal_arguments:
Internal arguments Internal arguments
------------------ ------------------
Both :ref:`module_replacer` and :ref:`Ansiballz` send additional arguments to Both :ref:`module_replacer` and :ref:`Ansiballz` send additional arguments to
the module beyond those which the user specified in the playbook. These the Ansible module beyond those which the user specified in the playbook. These
additional arguments are internal parameters that help implement global additional arguments are internal parameters that help implement global
Ansible features. Modules often do not need to know about these explicitly as Ansible features. Modules often do not need to know about these explicitly becau
the features are implemented in :py:mod:`ansible.module_utils.basic` but certain se
features need support from the module so it's good to know about them. the features are implemented in :py:mod:`ansible.module_utils.basic`. However, c
ertain
features need support from modules and some knowledge of the internal arguments
is useful.
The internal arguments listed here are global. If you need to add a local intern al argument to a custom module, create an action plugin for that specific module - see ``_original_basename`` in the `copy action plugin <https://github.com/ans ible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_ for an exampl e. The internal arguments in this section are global. If you need to add a local in ternal argument to a custom module, create an action plugin for that specific mo dule. See ``_original_basename`` in the `copy action plugin <https://github.com/ ansible/ansible/blob/devel/lib/ansible/plugins/action/copy.py#L329>`_ for an exa mple.
_ansible_no_log _ansible_no_log
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Boolean. Set to True whenever a parameter in a task or play specifies ``no_log`` Type: ``bool``
. Any module that calls :py:meth:`AnsibleModule.log` handles this automatically.
If a module implements its own logging then Set to ``True`` whenever an argument in a task or play specifies ``no_log``. Any
it needs to check this value. To access in a module, instantiate an module that calls the :py:meth:`AnsibleModule.log` function handles this action
``AnsibleModule`` and then check the value of :attr:`AnsibleModule.no_log`. automatically. If you have a module that implements its own logging then you ne
ed to check the value of ``_ansible_no_log``. To access ``_ansible_no_log`` in a
module, instantiate the ``AnsibleModule`` utility and then check the value of :
attr:`AnsibleModule.no_log`.
.. note:: .. note::
``no_log`` specified in a module's argument_spec is handled by a different m echanism. ``no_log`` specified in a module's ``argument_spec`` is handled by a differe nt mechanism.
_ansible_debug _ansible_debug
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Type: ``bool``
Boolean. Turns more verbose logging on or off and turns on logging of Operates verbose logging and logging of external commands that a module executes
external commands that the module executes. If a module uses . If the module uses the :py:meth:`AnsibleModule.debug` function rather than the
:py:meth:`AnsibleModule.debug` rather than :py:meth:`AnsibleModule.log` then :py:meth:`AnsibleModule.log` function then the messages are only logged if you
the messages are only logged if ``_ansible_debug`` is set to ``True``. set the ``_ansible_debug`` argument to ``True``. To access ``_ansible_debug`` in
To set, add ``debug: True`` to :file:`ansible.cfg` or set the environment a module, instantiate the ``AnsibleModule`` utility and access :attr:`AnsibleMo
variable :envvar:`ANSIBLE_DEBUG`. To access in a module, instantiate an dule._debug`. For more details, see :ref:`DEFAULT_DEBUG`.
``AnsibleModule`` and access :attr:`AnsibleModule._debug`.
_ansible_diff _ansible_diff
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Type: ``bool``
Boolean. If a module supports it, tells the module to show a unified diff of With this parameter you can configure your module to show a unified diff of chan
changes to be made to templated files. To set, pass the ``--diff`` command line ges that will be applied to the templated files. To access ``_ansible_diff`` in
option. To access in a module, instantiate an `AnsibleModule` and access a module, instantiate the ``AnsibleModule`` utility and access :attr:`AnsibleMod
:attr:`AnsibleModule._diff`. ule._diff`. You can also access this parameter using the ``diff`` keyword in you
r playbook, or the relevant environment variable. For more details, see :ref:`pl
aybook_keywords` and the :ref:`DIFF_ALWAYS` configuration option.
_ansible_verbosity _ansible_verbosity
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
Unused. This value could be used for finer grained control over logging. Type: ``int``
You can use this argument to control the level (0 for none) of verbosity in logg
ing.
_ansible_selinux_special_fs _ansible_selinux_special_fs
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
List. Names of filesystems which should have a special SELinux Type: ``list``
context. They are used by the `AnsibleModule` methods which operate on Elements: ``strings``
files (changing attributes, moving, and copying). To set, add a comma separated
string of filesystem names in :file:`ansible.cfg`: This argument provides modules with the names of file systems which should have
a special SELinux context. They are used by the ``AnsibleModule`` methods which
.. code-block:: ini operate on files (changing attributes, moving, and copying).
# ansible.cfg Most modules can use the built-in ``AnsibleModule`` methods to manipulate files.
[selinux] To access in a module that needs to know about these special context file syste
special_context_filesystems=nfs,vboxsf,fuse,ramfs,vfat ms, instantiate ``AnsibleModule`` and examine the list in :attr:`AnsibleModule._
selinux_special_fs`.
Most modules can use the built-in ``AnsibleModule`` methods to manipulate
files. To access in a module that needs to know about these special context file This argument replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` fro
systems, instantiate an ``AnsibleModule`` and examine the list in m :ref:`module_replacer`. In the module replacer framework the argument was form
:attr:`AnsibleModule._selinux_special_fs`. atted as a comma-separated string of file system names. Under the Ansiballz fram
ework it is a list. You can access ``_ansible_selinux_special_fs`` using the cor
This replaces :attr:`ansible.module_utils.basic.SELINUX_SPECIAL_FS` from responding environment variable. For more details, see the :ref:`DEFAULT_SELINUX
:ref:`module_replacer`. In module replacer it was a comma separated string of _SPECIAL_FS` configuration option.
filesystem names. Under Ansiballz it's an actual list.
.. versionadded:: 2.1 .. versionadded:: 2.1
_ansible_syslog_facility _ansible_syslog_facility
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
This parameter controls which syslog facility Ansible module logs to. To set, ch This argument controls which syslog facility the module logs to. Most modules sh
ange the ``syslog_facility`` value in :file:`ansible.cfg`. Most ould just use the :meth:`AnsibleModule.log` function which will then make use of
modules should just use :meth:`AnsibleModule.log` which will then make use of this. If a module has to use this on its own, it should instantiate the ``Ansib
this. If a module has to use this on its own, it should instantiate an leModule`` method and then retrieve the name of the syslog facility from :attr:`
`AnsibleModule` and then retrieve the name of the syslog facility from AnsibleModule._syslog_facility`. The Ansiballz code is less elegant than the :re
:attr:`AnsibleModule._syslog_facility`. The Ansiballz code is less hacky than th f:`module_replacer` code:
e old :ref:`module_replacer` code:
.. code-block:: python .. code-block:: python
# Old module_replacer way # Old module_replacer way
import syslog import syslog
syslog.openlog(NAME, 0, syslog.LOG_USER) syslog.openlog(NAME, 0, syslog.LOG_USER)
# New Ansiballz way # New Ansiballz way
import syslog import syslog
facility_name = module._syslog_facility facility_name = module._syslog_facility
facility = getattr(syslog, facility_name, syslog.LOG_USER) facility = getattr(syslog, facility_name, syslog.LOG_USER)
syslog.openlog(NAME, 0, facility) syslog.openlog(NAME, 0, facility)
For more details, see the :ref:`DEFAULT_SYSLOG_FACILITY` configuration option.
.. versionadded:: 2.1 .. versionadded:: 2.1
_ansible_version _ansible_version
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
This parameter passes the version of Ansible that runs the module. To access This argument passes the version of Ansible to the module. To access it, a modul
it, a module should instantiate an `AnsibleModule` and then retrieve it e should instantiate the ``AnsibleModule`` method and then retrieve the version
from :attr:`AnsibleModule.ansible_version`. This replaces from :attr:`AnsibleModule.ansible_version`. This replaces :attr:`ansible.module_
:attr:`ansible.module_utils.basic.ANSIBLE_VERSION` from utils.basic.ANSIBLE_VERSION` from :ref:`module_replacer`.
:ref:`module_replacer`.
.. versionadded:: 2.1 .. versionadded:: 2.1
_ansible_module_name
^^^^^^^^^^^^^^^^^^^^
Type: ``str``
This argument passes the information to modules about their name. For more detai
ls see, the configuration option :ref:`DEFAULT_MODULE_NAME`.
_ansible_string_conversion_action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This argument provides instructions about what modules should do after the value
s of the user-specified module parameters are converted to strings. For more det
ails, see the :ref:`STRING_CONVERSION_ACTION` configuration option.
_ansible_keep_remote_files
^^^^^^^^^^^^^^^^^^^^^^^^^^
Type: ``bool``
This argument provides instructions that modules must be ready if they need to k
eep the remote files. For more details, see the :ref:`DEFAULT_KEEP_REMOTE_FILES`
configuration option.
_ansible_socket
^^^^^^^^^^^^^^^
This argument provides modules with a socket for persistent connections. The arg
ument is created using the :ref:`PERSISTENT_CONTROL_PATH_DIR` configuration opti
on.
_ansible_shell_executable
^^^^^^^^^^^^^^^^^^^^^^^^^
Type: ``bool``
This argument ensures that modules use the designated shell executable. For more
details, see the :ref:`ansible_shell_executable` remote host environment parame
ter.
_ansible_tmpdir
^^^^^^^^^^^^^^^
Type: ``str``
This argument provides instructions to modules that all commands must use the de
signated temporary directory, if created. The action plugin designs this tempora
ry directory.
Modules can access this parameter by using the public ``tmpdir`` property. The `
`tmpdir`` property will create a temporary directory if the action plugin did no
t set the parameter.
The directory name is generated randomly, and the the root of the directory is d
etermined by one of these:
* :ref:`DEFAULT_LOCAL_TMP`
* `remote_tmp <https://docs.ansible.com/ansible/latest/collections/ansible/built
in/sh_shell.html#parameter-remote_tmp>`_
* `system_tmpdirs <https://docs.ansible.com/ansible/latest/collections/ansible/b
uiltin/sh_shell.html#parameter-system_tmpdirs>`_
As a result, using the ``ansible.cfg`` configuration file to activate or customi
ze this setting will not guarantee that you control the full value.
_ansible_remote_tmp
^^^^^^^^^^^^^^^^^^^
The module's ``tmpdir`` property creates a randomized directory name in this dir
ectory if the action plugin did not set ``_ansible_tmpdir``. For more details, s
ee the `remote_tmp <https://docs.ansible.com/ansible/latest/collections/ansible/
builtin/sh_shell.html#parameter-remote_tmp>`_ parameter of the shell plugin.
.. _flow_module_return_values: .. _flow_module_return_values:
Module return values & Unsafe strings Module return values & Unsafe strings
------------------------------------- -------------------------------------
At the end of a module's execution, it formats the data that it wants to return as a JSON string and prints the string to its stdout. The normal action plugin r eceives the JSON string, parses it into a Python dictionary, and returns it to t he executor. At the end of a module's execution, it formats the data that it wants to return as a JSON string and prints the string to its stdout. The normal action plugin r eceives the JSON string, parses it into a Python dictionary, and returns it to t he executor.
If Ansible templated every string return value, it would be vulnerable to an att ack from users with access to managed nodes. If an unscrupulous user disguised m alicious code as Ansible return value strings, and if those strings were then te mplated on the controller, Ansible could execute arbitrary code. To prevent this scenario, Ansible marks all strings inside returned data as ``Unsafe``, emittin g any Jinja2 templates in the strings verbatim, not expanded by Jinja2. If Ansible templated every string return value, it would be vulnerable to an att ack from users with access to managed nodes. If an unscrupulous user disguised m alicious code as Ansible return value strings, and if those strings were then te mplated on the controller, Ansible could execute arbitrary code. To prevent this scenario, Ansible marks all strings inside returned data as ``Unsafe``, emittin g any Jinja2 templates in the strings verbatim, not expanded by Jinja2.
Strings returned by invoking a module through ``ActionPlugin._execute_module()`` are automatically marked as ``Unsafe`` by the normal action plugin. If another action plugin retrieves information from a module through some other means, it m ust mark its return data as ``Unsafe`` on its own. Strings returned by invoking a module through ``ActionPlugin._execute_module()`` are automatically marked as ``Unsafe`` by the normal action plugin. If another action plugin retrieves information from a module through some other means, it m ust mark its return data as ``Unsafe`` on its own.
 End of changes. 20 change blocks. 
62 lines changed or deleted 146 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)