diff options
| -rw-r--r-- | docs/docsite/rst/plugins/action.rst | 21 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/become.rst | 18 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/cache.rst | 27 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/callback.rst | 28 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/cliconf.rst | 2 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/connection.rst | 22 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/docs_fragment.rst | 35 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/filter.rst | 41 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/httpapi.rst | 2 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/inventory.rst | 25 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/lookup.rst | 12 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/module.rst | 43 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/module_util.rst | 35 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/netconf.rst | 2 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/plugins.rst | 14 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/shell.rst | 18 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/strategy.rst | 23 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/terminal.rst | 6 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/test.rst | 46 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/vars.rst | 28 |
20 files changed, 315 insertions, 133 deletions
diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst index 1ce16ea2ae..ff8eaf6522 100644 --- a/docs/docsite/rst/plugins/action.rst +++ b/docs/docsite/rst/plugins/action.rst @@ -1,16 +1,15 @@ .. _action_plugins: -Action Plugins +Action plugins ============== .. contents:: :local: :depth: 2 -Action plugins act in conjunction with :ref:`modules <working_with_modules>` to execute the actions required by playbook tasks. -They usually execute automatically in the background doing prerequisite work before modules execute. +Action plugins act in conjunction with :ref:`modules <working_with_modules>` to execute the actions required by playbook tasks. They usually execute automatically in the background doing prerequisite work before modules execute. -The 'normal' action plugin is used for modules that do not already have an action plugin. +The 'normal' action plugin is used for modules that do not already have an action plugin. If necessary, you can :ref:`create custom action plugins <developing_actions>`. .. _enabling_action: @@ -37,19 +36,19 @@ Use ``ansible-doc <name>`` to see specific documentation and examples, this shou .. seealso:: :ref:`cache_plugins` - Ansible Cache plugins + Cache plugins :ref:`callback_plugins` - Ansible callback plugins + Callback plugins :ref:`connection_plugins` - Ansible connection plugins + Connection plugins :ref:`inventory_plugins` - Ansible inventory plugins + Inventory plugins :ref:`shell_plugins` - Ansible Shell plugins + Shell plugins :ref:`strategy_plugins` - Ansible Strategy plugins + Strategy plugins :ref:`vars_plugins` - Ansible Vars plugins + Vars plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/become.rst b/docs/docsite/rst/plugins/become.rst index f46d50d813..f40a7bfa2e 100644 --- a/docs/docsite/rst/plugins/become.rst +++ b/docs/docsite/rst/plugins/become.rst @@ -1,6 +1,6 @@ .. _become_plugins: -Become Plugins +Become plugins ============== .. contents:: @@ -52,15 +52,15 @@ Use ``ansible-doc -t become <plugin name>`` to see specific documentation and ex :ref:`about_playbooks` An introduction to playbooks :ref:`inventory_plugins` - Ansible inventory plugins + Inventory plugins :ref:`callback_plugins` - Ansible callback plugins - :ref:`playbooks_filters` - Jinja2 filter plugins - :ref:`playbooks_tests` - Jinja2 test plugins - :ref:`playbooks_lookups` - Jinja2 lookup plugins + Callback plugins + :ref:`filter_plugins` + Filter plugins + :ref:`test_plugins` + Test plugins + :ref:`lookup_plugins` + Lookup plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index b36092961d..459bbb779a 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -1,6 +1,6 @@ .. _cache_plugins: -Cache Plugins +Cache plugins ============= .. contents:: @@ -11,11 +11,11 @@ Cache plugins allow Ansible to store gathered facts or inventory source data wit The default cache plugin is the :ref:`memory <memory_cache>` plugin, which only caches the data for the current execution of Ansible. Other plugins with persistent storage are available to allow caching the data across runs. Some of these cache plugins write to files, others write to databases. -You can use different cache plugins for inventory and facts. If you enable inventory caching without setting an inventory-specific cache plugin, Ansible uses the fact cache plugin for both facts and inventory. +You can use different cache plugins for inventory and facts. If you enable inventory caching without setting an inventory-specific cache plugin, Ansible uses the fact cache plugin for both facts and inventory. If necessary, you can :ref:`create custom cache plugins <developing_cache_plugins>`. .. _enabling_cache: -Enabling Fact Cache Plugins +Enabling fact cache plugins --------------------------- Fact caching is always enabled. However, only one fact cache plugin can be active at a time. You can select the cache plugin to use for fact caching in the Ansible configuration, either with an environment variable: @@ -42,8 +42,7 @@ To enable a custom cache plugin, save it in a ``cache_plugins`` directory adjace You also need to configure other settings specific to each plugin. Consult the individual plugin documentation or the Ansible :ref:`configuration <ansible_configuration_settings>` for more details. - -Enabling Inventory Cache Plugins +Enabling inventory cache plugins -------------------------------- Inventory caching is disabled by default. To cache inventory data, you must enable inventory caching and then select the specific cache plugin you want to use. Not all inventory plugins support caching, so check the documentation for the inventory plugin(s) you want to use. You can enable inventory caching with an environment variable: @@ -104,7 +103,7 @@ If you enable caching for inventory plugins without selecting an inventory-speci .. _using_cache: -Using Cache Plugins +Using cache plugins ------------------- Cache plugins are used automatically once they are enabled. @@ -112,7 +111,7 @@ Cache plugins are used automatically once they are enabled. .. _cache_plugin_list: -Plugin List +Plugin list ----------- You can use ``ansible-doc -t cache -l`` to see the list of available plugins. @@ -121,19 +120,19 @@ Use ``ansible-doc -t cache <plugin name>`` to see specific documentation and exa .. seealso:: :ref:`action_plugins` - Ansible Action plugins + Action plugins :ref:`callback_plugins` - Ansible callback plugins + Callback plugins :ref:`connection_plugins` - Ansible connection plugins + Connection plugins :ref:`inventory_plugins` - Ansible inventory plugins + Inventory plugins :ref:`shell_plugins` - Ansible Shell plugins + Shell plugins :ref:`strategy_plugins` - Ansible Strategy plugins + Strategy plugins :ref:`vars_plugins` - Ansible Vars plugins + Vars plugins `User Mailing List <https://groups.google.com/forum/#!forum/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index fc26daf324..5d35d3a825 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -1,23 +1,20 @@ .. _callback_plugins: -Callback Plugins +Callback plugins ================ .. contents:: :local: :depth: 2 -Callback plugins enable adding new behaviors to Ansible when responding to events. -By default, callback plugins control most of the output you see when running the command line programs, -but can also be used to add additional output, integrate with other tools and marshall the events to a storage backend. +Callback plugins enable adding new behaviors to Ansible when responding to events. By default, callback plugins control most of the output you see when running the command line programs, but can also be used to add additional output, integrate with other tools and marshal the events to a storage backend. If necessary, you can :ref:`create custom callback plugins <developing_callbacks>`. .. _callback_examples: Example callback plugins ------------------------ -The :ref:`log_plays <log_plays_callback>` callback is an example of how to record playbook events to a log file, -and the :ref:`mail <mail_callback>` callback sends email on playbook failures. +The :ref:`log_plays <log_plays_callback>` callback is an example of how to record playbook events to a log file, and the :ref:`mail <mail_callback>` callback sends email on playbook failures. The :ref:`say <say_callback>` callback responds with computer synthesized speech in relation to playbook events. @@ -26,7 +23,7 @@ The :ref:`say <say_callback>` callback responds with computer synthesized speech Enabling callback plugins ------------------------- -You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the callback directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`. +You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the callback directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`. Plugins are loaded in alphanumeric order. For example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`. @@ -56,8 +53,7 @@ This only affects :ref:`ansible-playbook` by default. Setting a callback plugin for ad hoc commands --------------------------------------------- -The :ref:`ansible` ad hoc command specifically uses a different callback plugin for stdout, -so there is an extra setting in :ref:`ansible_configuration_settings` you need to add to use the stdout callback defined above: +The :ref:`ansible` ad hoc command specifically uses a different callback plugin for stdout, so there is an extra setting in :ref:`ansible_configuration_settings` you need to add to use the stdout callback defined above: .. code-block:: ini @@ -82,19 +78,19 @@ Use ``ansible-doc -t callback <plugin name>`` to see specific documents and exam .. seealso:: :ref:`action_plugins` - Ansible Action plugins + Action plugins :ref:`cache_plugins` - Ansible cache plugins + Cache plugins :ref:`connection_plugins` - Ansible connection plugins + Connection plugins :ref:`inventory_plugins` - Ansible inventory plugins + Inventory plugins :ref:`shell_plugins` - Ansible Shell plugins + Shell plugins :ref:`strategy_plugins` - Ansible Strategy plugins + Strategy plugins :ref:`vars_plugins` - Ansible Vars plugins + Vars plugins `User Mailing List <https://groups.google.com/forum/#!forum/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/cliconf.rst b/docs/docsite/rst/plugins/cliconf.rst index 61f96d9046..f5af78c212 100644 --- a/docs/docsite/rst/plugins/cliconf.rst +++ b/docs/docsite/rst/plugins/cliconf.rst @@ -1,6 +1,6 @@ .. _cliconf_plugins: -Cliconf Plugins +Cliconf plugins =============== .. contents:: diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 495f937f11..ed437a6190 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -1,6 +1,6 @@ .. _connection_plugins: -Connection Plugins +Connection plugins ================== .. contents:: @@ -9,7 +9,7 @@ Connection Plugins Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. -By default, Ansible ships with several plugins. The most commonly used are the :ref:`paramiko SSH<paramiko_ssh_connection>`, native ssh (just called :ref:`ssh<ssh_connection>`), and :ref:`local<local_connection>` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. +By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH<paramiko_ssh_connection>`, native ssh (just called :ref:`ssh<ssh_connection>`), and :ref:`local<local_connection>` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins <developing_connection_plugins>`. The basics of these connection types are covered in the :ref:`getting started<intro_getting_started>` section. @@ -51,7 +51,7 @@ Each plugin might also have a specific version of a variable that overrides the .. _connection_plugin_list: -Plugin List +Plugin list ----------- You can use ``ansible-doc -t connection -l`` to see the list of available plugins. @@ -63,15 +63,15 @@ Use ``ansible-doc -t connection <plugin name>`` to see detailed documentation an :ref:`Working with Playbooks<working_with_playbooks>` An introduction to playbooks :ref:`callback_plugins` - Ansible callback plugins - :ref:`Filters<playbooks_filters>` - Jinja2 filter plugins - :ref:`Tests<playbooks_tests>` - Jinja2 test plugins - :ref:`Lookups<playbooks_lookups>` - Jinja2 lookup plugins + Callback plugins + :ref:`filter_plugins` + Filter plugins + :ref:`test_plugins` + Test plugins + :ref:`lookup_plugins` + Lookup plugins :ref:`vars_plugins` - Ansible vars plugins + Vars plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/docs_fragment.rst b/docs/docsite/rst/plugins/docs_fragment.rst new file mode 100644 index 0000000000..d28800394a --- /dev/null +++ b/docs/docsite/rst/plugins/docs_fragment.rst @@ -0,0 +1,35 @@ +.. _docs_fragment_plugins: + +Docs fragments +============== + +.. contents:: + :local: + :depth: 2 + +Docs fragments allow you to document common parameters of multiple plugins or modules in a single place. + +.. _enabling_docs_fragments: + +Enabling docs fragments +----------------------- + +You can add a custom docs fragment by dropping it into a ``doc_fragments`` directory adjacent to your collection or role, just like any other plugin. + +.. _using_docs_fragments: + +Using docs fragments +-------------------- + +Only collection developers and maintainers use docs fragments. For more information on using docs fragments, see :ref:`module_docs_fragments` or :ref:`docfragments_collections`. + +.. seealso:: + + :ref:`developing_modules_general` + An introduction to creating Ansible modules + :ref:`developing_collections` + An guide to creating Ansible collections + `User Mailing List <https://groups.google.com/group/ansible-devel>`_ + Have a question? Stop by the google group! + `irc.libera.chat <https://libera.chat/>`_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/filter.rst b/docs/docsite/rst/plugins/filter.rst new file mode 100644 index 0000000000..429abb5d1a --- /dev/null +++ b/docs/docsite/rst/plugins/filter.rst @@ -0,0 +1,41 @@ +.. _filter_plugins: + +Filter plugins +============== + +.. contents:: + :local: + :depth: 2 + +Filter plugins manipulate data. With the right filter you can extract a particular value, transform data types and formats, perform mathematical calculations, split and concatenate strings, insert dates and times, and do much more. Ansible leverages the :ref:`standard filters <jinja2:builtin-filters>` shipped with Jinja2 and adds some specialized filter plugins. You can :ref:`create custom Ansible filters as plugins <developing_filter_plugins>`. + +.. _enabling_filter: + +Enabling filter plugins +----------------------- + +You can add a custom filter plugin by dropping it into a ``filter_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the filter plugin directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`. + +.. _using_filter: + +Using filter plugins +-------------------- + +For information on using filter plugins, see :ref:`playbooks_filters`. + +.. seealso:: + + :ref:`about_playbooks` + An introduction to playbooks + :ref:`inventory_plugins` + Inventory plugins + :ref:`callback_plugins` + Callback plugins + :ref:`test_plugins` + Test plugins + :ref:`lookup_plugins` + Lookup plugins + `User Mailing List <https://groups.google.com/group/ansible-devel>`_ + Have a question? Stop by the google group! + `irc.libera.chat <https://libera.chat/>`_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/httpapi.rst b/docs/docsite/rst/plugins/httpapi.rst index a0e1725f5c..7ce0573b91 100644 --- a/docs/docsite/rst/plugins/httpapi.rst +++ b/docs/docsite/rst/plugins/httpapi.rst @@ -1,6 +1,6 @@ .. _httpapi_plugins: -Httpapi Plugins +Httpapi plugins =============== .. contents:: diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 91c520ad08..a8ef2e987e 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -1,14 +1,13 @@ .. _inventory_plugins: -Inventory Plugins +Inventory plugins ================= .. contents:: :local: :depth: 2 -Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either using the ``-i /path/to/file`` and/or ``-i 'host1, host2'`` command line parameters or from other configuration sources. - +Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either using the ``-i /path/to/file`` and/or ``-i 'host1, host2'`` command line parameters or from other configuration sources. If necessary, you can :ref:`create custom inventory plugins <developing_inventory_plugins>`. .. _enabling_inventory: @@ -134,7 +133,7 @@ Here is an example of setting inventory caching with some fact caching defaults .. _inventory_plugin_list: -Plugin List +Plugin list ----------- You can use ``ansible-doc -t inventory -l`` to see the list of available plugins. @@ -145,17 +144,17 @@ Use ``ansible-doc -t inventory <plugin name>`` to see plugin-specific documentat :ref:`about_playbooks` An introduction to playbooks :ref:`callback_plugins` - Ansible callback plugins + Callback plugins :ref:`connection_plugins` - Ansible connection plugins - :ref:`playbooks_filters` - Jinja2 filter plugins - :ref:`playbooks_tests` - Jinja2 test plugins - :ref:`playbooks_lookups` - Jinja2 lookup plugins + Connection plugins + :ref:`filter_plugins` + Filter plugins + :ref:`test_plugins` + Test plugins + :ref:`lookup_plugins` + Lookup plugins :ref:`vars_plugins` - Ansible vars plugins + Vars plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst index 59f508437a..1ad3ae9057 100644 --- a/docs/docsite/rst/plugins/lookup.rst +++ b/docs/docsite/rst/plugins/lookup.rst @@ -1,13 +1,13 @@ .. _lookup_plugins: -Lookup Plugins +Lookup plugins ============== .. contents:: :local: :depth: 2 -Lookup plugins are an Ansible-specific extension to the Jinja2 templating language. You can use lookup plugins to access data from outside sources (files, databases, key/value stores, APIs, and other services) within your playbooks. Like all :ref:`templating <playbooks_templating>`, lookups execute and are evaluated on the Ansible control machine. Ansible makes the data returned by a lookup plugin available using the standard templating system. You can use lookup plugins to load variables or templates with information from external sources. +Lookup plugins are an Ansible-specific extension to the Jinja2 templating language. You can use lookup plugins to access data from outside sources (files, databases, key/value stores, APIs, and other services) within your playbooks. Like all :ref:`templating <playbooks_templating>`, lookups execute and are evaluated on the Ansible control machine. Ansible makes the data returned by a lookup plugin available using the standard templating system. You can use lookup plugins to load variables or templates with information from external sources. You can :ref:`create custom lookup plugins <developing_lookup_plugins>`. .. note:: - Lookups are executed with a working directory relative to the role or play, @@ -32,7 +32,7 @@ Ansible enables all lookup plugins it can find. You can activate a custom lookup Using lookup plugins -------------------- -You can use lookup plugins anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :ref:`template <template_module>` module. +You can use lookup plugins anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :ref:`template <template_module>` module. For more information on using lookup plugins, see :ref:`playbooks_lookups`. .. code-block:: YAML+Jinja @@ -147,12 +147,10 @@ You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. U Ansible inventory plugins :ref:`callback_plugins` Ansible callback plugins - :ref:`playbooks_filters` + :ref:`filter_plugins` Jinja2 filter plugins - :ref:`playbooks_tests` + :ref:`test_plugins` Jinja2 test plugins - :ref:`playbooks_lookups` - Jinja2 lookup plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/module.rst b/docs/docsite/rst/plugins/module.rst new file mode 100644 index 0000000000..4d44f46979 --- /dev/null +++ b/docs/docsite/rst/plugins/module.rst @@ -0,0 +1,43 @@ +.. _module_plugins: + +Modules +======= + +.. contents:: + :local: + :depth: 2 + +Modules are the main building blocks of Ansible playbooks. Although we do not generally speak of "module plugins", a module is a type of plugin. For a developer-focused description of the differences between modules and other plugins, see :ref:`modules_vs_plugins`. + +.. _enabling_modules: + +Enabling modules +---------------- + +You can enable a custom module by dropping it into one of these locations: + +* any directory added to the ``ANSIBLE_LIBRARY`` environment variable (``$ANSIBLE_LIBRARY`` takes a colon-separated list like ``$PATH``) +* ``~/.ansible/plugins/modules/`` +* ``/usr/share/ansible/plugins/modules/`` + +For more information on using local custom modules, see :ref:`local_modules`. + +.. _using_modules: + +Using modules +------------- + +For information on using modules in ad hoc tasks, see :ref:`intro_adhoc`. For information on using modules in playbooks, see :ref:`playbooks_intro`. + +.. seealso:: + + :ref:`about_playbooks` + An introduction to playbooks + :ref:`developing_modules_general` + An introduction to creating Ansible modules + :ref:`developing_collections` + An guide to creating Ansible collections + `User Mailing List <https://groups.google.com/group/ansible-devel>`_ + Have a question? Stop by the google group! + `irc.libera.chat <https://libera.chat/>`_ + #ansible-devel IRC chat channel diff --git a/docs/docsite/rst/plugins/module_util.rst b/docs/docsite/rst/plugins/module_util.rst new file mode 100644 index 0000000000..c694380c6d --- /dev/null +++ b/docs/docsite/rst/plugins/module_util.rst @@ -0,0 +1,35 @@ +.. _module_util_plugins: + +Module utilities +================ + +.. contents:: + :local: + :depth: 2 + +Module utilities contain shared code used by multiple plugins. You can write :ref:`custom module utilities <developing_module_utilities>`. + +.. _enabling_module_utils: + +Enabling module utilities +------------------------- + +You can add a custom module utility by dropping it into a ``module_utils`` directory adjacent to your collection or role, just like any other plugin. + +.. _using_module_utils: + +Using module utilities +---------------------- + +For information on using module utilities, see :ref:`developing_module_utilities`. + +.. seealso:: + + :ref:`developing_modules_general` + An introduction to creating Ansible modules + :ref:`developing_collections` + An guide to creating Ansible collections + `User Mailing List <https://groups.google.com/group/ansible-devel>`_ + Have a question? Stop by the google group! + `irc.libera.chat <https://libera.chat/>`_ + #ansible-devel IRC chat channel diff --git a/docs/docsite/rst/plugins/netconf.rst b/docs/docsite/rst/plugins/netconf.rst index 908eec9020..4f79809d12 100644 --- a/docs/docsite/rst/plugins/netconf.rst +++ b/docs/docsite/rst/plugins/netconf.rst @@ -1,6 +1,6 @@ .. _netconf_plugins: -Netconf Plugins +Netconf plugins =============== .. contents:: diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst index 2a2c632253..53b8d21ccb 100644 --- a/docs/docsite/rst/plugins/plugins.rst +++ b/docs/docsite/rst/plugins/plugins.rst @@ -1,7 +1,7 @@ .. _plugins_lookup: ******************** -Working With Plugins +Working with plugins ******************** Plugins are pieces of code that augment Ansible's core functionality. Ansible uses a plugin architecture to enable a rich, flexible and expandable feature set. @@ -19,22 +19,24 @@ This section covers the various types of plugins that are included with Ansible: callback cliconf connection + docs_fragment + filter httpapi inventory lookup + module + module_util netconf shell strategy terminal + test vars - ../user_guide/playbooks_filters - ../user_guide/playbooks_tests - ../user_guide/plugin_filtering_config .. seealso:: - :ref:`about_playbooks` - An introduction to playbooks + :ref:`plugin_filtering_config` + Controlling access to modules :ref:`ansible_configuration_settings` Ansible configuration documentation and settings :ref:`command_line_tools` diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index 09dbfc279d..d1802c1f0b 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/docs/docsite/rst/plugins/shell.rst @@ -1,6 +1,6 @@ .. _shell_plugins: -Shell Plugins +Shell plugins ============= .. contents:: @@ -38,15 +38,15 @@ detailed in the plugin themselves (linked below). :ref:`about_playbooks` An introduction to playbooks :ref:`inventory_plugins` - Ansible inventory plugins + Inventory plugins :ref:`callback_plugins` - Ansible callback plugins - :ref:`playbooks_filters` - Jinja2 filter plugins - :ref:`playbooks_tests` - Jinja2 test plugins - :ref:`playbooks_lookups` - Jinja2 lookup plugins + Callback plugins + :ref:`filter_plugins` + Filter plugins + :ref:`test_plugins` + Test plugins + :ref:`lookup_plugins` + Lookup plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst index c4a4a500d3..a31e26179a 100644 --- a/docs/docsite/rst/plugins/strategy.rst +++ b/docs/docsite/rst/plugins/strategy.rst @@ -1,13 +1,13 @@ .. _strategy_plugins: -Strategy Plugins +Strategy plugins ================ .. contents:: :local: :depth: 2 -Strategy plugins control the flow of play execution by handling task and host scheduling. +Strategy plugins control the flow of play execution by handling task and host scheduling. For more information on using strategy plugins and other ways to control execution order, see :ref:`playbooks_strategies`. .. _enable_strategy: @@ -22,8 +22,7 @@ putting it in one of the lookup directory sources configured in :ref:`ansible.cf Using strategy plugins ---------------------- -Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run. -The default is the :ref:`linear <linear_strategy>` plugin. You can change this default in Ansible :ref:`configuration <ansible_configuration_settings>` using an environment variable: +Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run. By default Ansible uses the :ref:`linear <linear_strategy>` plugin. You can change this default in Ansible :ref:`configuration <ansible_configuration_settings>` using an environment variable: .. code-block:: shell @@ -64,15 +63,15 @@ Use ``ansible-doc -t strategy <plugin name>`` to see plugin-specific specific do :ref:`about_playbooks` An introduction to playbooks :ref:`inventory_plugins` - Ansible inventory plugins + Inventory plugins :ref:`callback_plugins` - Ansible callback plugins - :ref:`playbooks_filters` - Jinja2 filter plugins - :ref:`playbooks_tests` - Jinja2 test plugins - :ref:`playbooks_lookups` - Jinja2 lookup plugins + Callback plugins + :ref:`filter_plugins` + Filter plugins + :ref:`test_plugins` + Test plugins + :ref:`lookup_plugins` + Lookup plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/terminal.rst b/docs/docsite/rst/plugins/terminal.rst index 006b75235b..010805f76c 100644 --- a/docs/docsite/rst/plugins/terminal.rst +++ b/docs/docsite/rst/plugins/terminal.rst @@ -1,6 +1,6 @@ .. _terminal_plugins: -Terminal Plugins +Terminal plugins ================ .. contents:: @@ -23,7 +23,7 @@ You can extend Ansible to support other network devices by dropping a custom plu Using terminal plugins ------------------------ -The terminal plugin to use is determined automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality. +Ansible determines which terminal plugin to use automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality. Terminal plugins operate without configuration. All options to control the terminal are exposed in the ``network_cli`` connection plugin. @@ -41,6 +41,8 @@ These plugins have migrated to collections on `Ansible Galaxy <https://galaxy.an :ref:`Ansible for Network Automation<network_guide>` An overview of using Ansible to automate networking devices. + :ref:`connection_plugins` + Connection plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ diff --git a/docs/docsite/rst/plugins/test.rst b/docs/docsite/rst/plugins/test.rst new file mode 100644 index 0000000000..0e9916ce4c --- /dev/null +++ b/docs/docsite/rst/plugins/test.rst @@ -0,0 +1,46 @@ +.. _test_plugins: + +Test plugins +============= + +.. contents:: + :local: + :depth: 2 + +Test plugins evaluate template expressions and return True or False. With test plugins you can create :ref:`conditionals <playbooks_conditionals>` to implement the logic of your tasks, blocks, plays, playbooks, and roles. Ansible leverages the `standard tests `_ shipped as part of Jinja, and adds some specialized test plugins. You can :ref:`create custom Ansible test plugins <developing_test_plugins>`. + +.. _standard tests: https://jinja.palletsprojects.com/en/latest/templates/#builtin-tests + +.. _enabling_test: + +Enabling test plugins +---------------------- + +You can add a custom test plugin by dropping it into a ``test_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the test plugin directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`. + + +.. _using_test: + +Using test plugins +------------------- + +The User Guide offers detailed documentation on :ref:`using test plugins <playbooks_tests>`. + +.. seealso:: + + :ref:`about_playbooks` + An introduction to playbooks + :ref:`playbooks_tests` + Using tests + :ref:`playbooks_conditionals` + Using conditional statements + :ref:`filter_plugins` + Filter plugins + :ref:`playbooks_filters` + Using filters + :ref:`lookup_plugins` + Lookup plugins + `User Mailing List <https://groups.google.com/group/ansible-devel>`_ + Have a question? Stop by the google group! + `irc.libera.chat <https://libera.chat/>`_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst index 626c7de9bb..c0f1043e3e 100644 --- a/docs/docsite/rst/plugins/vars.rst +++ b/docs/docsite/rst/plugins/vars.rst @@ -1,19 +1,18 @@ .. _vars_plugins: -Vars Plugins +Vars plugins ============ .. contents:: :local: :depth: 2 -Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins. +Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins. For more details about variables in Ansible, see :ref:`playbooks_variables`. Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. The :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_variables` and :ref:`group_variables`. - .. _enable_vars: Enabling vars plugins @@ -50,29 +49,18 @@ You can also control vars plugin execution on a per-plugin basis for vars plugin .. _vars_plugin_list: -Plugin Lists ------------- +Plugin list +----------- -You can use ``ansible-doc -t vars -l`` to see the list of available plugins. -Use ``ansible-doc -t vars <plugin name>`` to see specific plugin-specific documentation and examples. +You can use ``ansible-doc -t vars -l`` to see the list of available vars plugins. Use ``ansible-doc -t vars <plugin name>`` to see plugin-specific documentation and examples. .. seealso:: - :ref:`action_plugins` - Ansible Action plugins :ref:`cache_plugins` - Ansible Cache plugins - :ref:`callback_plugins` - Ansible callback plugins - :ref:`connection_plugins` - Ansible connection plugins - :ref:`inventory_plugins` - Ansible inventory plugins - :ref:`shell_plugins` - Ansible Shell plugins - :ref:`strategy_plugins` - Ansible Strategy plugins + Cache plugins + :ref:`lookup_plugins` + Lookup plugins `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.libera.chat <https://libera.chat/>`_ |