ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-22 04:40:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

updated plugin docs (#30490)

Browse source 
* updated  docs

- for devs:
  - added inventory/vars section
  - made some updates to general section and other plugin types
- for users:
 - added 'user' plugin section to start describing the plugins
 - docs on types, what they are and how to use

- removed ref to deleted AUTHORS file
- corrected several typos/headers
- added descriptions to config.rst template
- ignore generated files for cli/plugins and config
- remove new generated files on `make clean`
- moved details from devguid and intro doc to plugin specific pages
- pretied up lookup notes
- changed precedence ref to not conflict config
- removed duplicate config data, as config is autogenerated and up to date
- put new plugins under playbooks
- added `pass` cause rst/python dislikes fractions
- removed dupe in .gitignore, alpha sorted to avoid moar dupes
- added try cause rst/python freaks out

* generate plugins into their own dir

only do plugins that support docs
use toctree from main plugins page
This commit is contained in:
Brian Coca 2017-09-22 23:19:50 -04:00 • committed by GitHub
commit b233f3f296
23 changed files with 873 additions and 1360 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/docsite/rst/plugins/action.rst Normal file
View file

@ -0,0 +1,36 @@
Action Plugins
---------------
These plugins act in conjunction with :doc:`modules <../modules>` to execute the actions required by playbook tasks.
They mostly execute automatically in the background doing prerequisite work for the modules of the same to be able to execute.
The 'normal' action plugin takes care of modules that do not already have an action plugin.
Enabling Vars Plugins
+++++++++++++++++++++
You can activate a custom action plugins by either dropping it into a ``action_plugins`` directory adjacent to your play or inside a role
or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
.. seealso::
:doc:`cache`
Ansible Cache plugins
:doc:`callback`
Ansible callback plugins
:doc:`connection`
Ansible connection plugins
:doc:`inventory`
Ansible inventory plugins
:doc:`shell`
Ansible Shell plugins
:doc:`strategy`
Ansible Strategy plugins
:doc:`vars`
Ansible Vars plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

65
docs/docsite/rst/plugins/cache.rst Normal file
View file

@ -0,0 +1,65 @@
.. contents:: Topics
Cache Plugins
-------------
This plugin implelents a backend caching mechanism for Ansible to store gathered facts or inventory source data
to avoid the cost of retrieving them from source.
The default plugin is the :doc:`memory <cache/memory>` plugin which will only cache the data for the current execution of Ansible.
Other plugins with persistent storage are available to allow caching the data across runs.
Enabling Cache Plugins
++++++++++++++++++++++
Only one cache plugin can be active at a time.
You can enable in configuration, either via environment variable:
.. code-block:: shell
export ANSIBLE_CACHE_PLUGIN=jsonfile
or in the ``ansible.cfg`` file:
.. code-block:: ini
[defaults]
fact_caching=redis
You will also need to setup other settings specific to each plugin, you can check the individual plugin documenattion
or the ansible :doc:`configuration <../config>` for more details.
Plugin List
+++++++++++
You can use ``ansible-doc -t cache -l`` to see the list of available plugins,
use ``ansible-doc -t cache <plugin name>`` to see specific documents and examples.
.. toctree:: :maxdepth: 1
:glob:
cache/*
.. seealso::
:doc:`action`
Ansible Action plugins
:doc:`callback`
Ansible callback plugins
:doc:`connection`
Ansible connection plugins
:doc:`inventory`
Ansible inventory plugins
:doc:`shell`
Ansible Shell plugins
:doc:`strategy`
Ansible Strategy plugins
:doc:`vars`
Ansible Vars plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

107
docs/docsite/rst/plugins/callback.rst Normal file
View file

@ -0,0 +1,107 @@
.. contents:: Topics
Callback Plugins
----------------
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_examples:
Example Callback Plugins
++++++++++++++++++++++++
The :doc:`log_plays <callback/log_plays>` callback is an example of how to record playbook events to a log file,
and the :doc:`mail callback/mail` callback sends email on playbook failures.
The :doc:`osx_say <callback/oxs_say>` callback provided is particularly entertaining --
it will respond with computer synthesized speech on OS X in relation to playbook events,
and is guaranteed to entertain and/or annoy coworkers.
.. _enabling_callbacks:
Enabling Callback Plugins
++++++++++++++++++++++++++
You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play or inside a role
or by putting it in one of the callback directory sources configured in :doc:`ansible.cfg <../config>`.
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`.
Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your :doc:`ansible.cfg <../config>` file in order to function.
For example:
.. code-block:: ini
#callback_whitelist = timer, mail, profile_roles
Managing stdout
```````````````
You can only have one plugin be the main manager of your console output. If you want to replace the default, you should define CALLBACK_TYPE = stdout in the subclass and then configure the stdout plugin in :doc:`ansible.cfg <../config>`. For example:
.. code-block:: ini
stdout_callback = dense
or for my custom callback:
.. code-block:: ini
stdout_callback = mycallback
This only affects :doc:`../ansible-playbook` by default.
Managing AdHoc
``````````````
The :doc:`ansible <../ansible>` AdHoc command speifically uses a different callback plugin for stdout,
so there is an extra setting you need to enable it to use the stdout callback defined above, in :doc:`ansible.cfg <../config>`:
.. code-block:: ini
[defaults]
bin_ansible_callbacks=True
or as an environment variable:
.. code-block:: shell
export ANSIBLE_LOAD_CALLBACK_PLUGINS=1
Plugin List
+++++++++++
You can use ``ansible-doc -t callback -l`` to see the list of available plugins,
use ``ansible-doc -t callback <plugin name>`` to see specific documents and examples.
.. toctree:: :maxdepth: 1
:glob:
callback/*
.. seealso::
:doc:`../playbooks`
An introduction to playbooks
:doc:`inventory`
Ansible inventory plugins
:doc:`../playbooks_filters`
Jinja2 filter plugins
:doc:`../playbooks_tests`
Jinja2 test plugins
:doc:`../playbooks_lookups`
Jinja2 lookup plugins
:doc:`vars`
Ansible vars plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

83
docs/docsite/rst/plugins/connection.rst Normal file
View file

@ -0,0 +1,83 @@
.. contents:: Topics
Connection Plugins
------------------
These plugins are in charge of enabling Ansible to connect to the target hosts so it can execute tasks on them.
Ansible ships we many connection plugins but only one can be used per host at a time.
By default, the configuration uses a 'smart' value, which means Ansible will decide to use the 'ssh' or 'paramiko' (python version of ssh client)
depending on what it detects on your system capabilities, it normally chooses 'ssh' if OpenSSH supports ControlPersist.
The basics of these connection types are covered in the :doc:`../intro_getting_started` section.
.. contents:: Topics
.. _ssh_plugins:
The ssh Plugins
++++++++++++++++
Since ssh is the default protocol used in system administration it is also the most used and prevalent in Ansible,
so much so that ssh options are included in the command line tools unlike other plugins, see :doc:`../ansible-playbook` for more details.
.. _using_connection_plugins:
Using Connection Plugins
++++++++++++++++++++++++
The transport can be changed via :doc:`configuration <../config>`, in the command line (``-c``, ``--connection``), as a keyword (:ref:`connection`)
in your play or by setting the a connection variable (:ref:`ansible_connection`), most often, in your inventory.
For example, for windows machines you might want o use the :doc:`winrm <connection/winrm>` plugin instead.
Most connection plugins can operate with a minimum configuration, by defaul they use the :ref:`inventory_hostname` and defaults to find the target host.
Each plugin documents it's configuration options and how to set, the following are 'connection variables' common to most:
:ref:ansible_host
The name of the host to connect to, if different from the :ref:`inventory_hostname`.
:ref:ansible_port
The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` it defaults to 22.
:ref:ansible_user
The default user name to log in as, most plugins defaul to the 'current user running Ansible'
Each plugin might also have a specific version that overrides the general one. i.e :ref:`ansible_ssh_host` for the :doc:`ssh <connection/ssh>` plugin.
Enabling Connection Plugins
+++++++++++++++++++++++++++
Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as dropping a custom plugin
into the ``connection_plugins`` directory.
Plugin List
+++++++++++
You can use ``ansible-doc -t connection -l`` to see the list of available plugins,
use ``ansible-doc -t connection <plugin name>`` to examine detailed documentation and examples.
.. toctree:: :maxdepth: 1
:glob:
connection/*
.. seealso::
:doc:`../playbooks`
An introduction to playbooks
:doc:`callback`
Ansible callback plugins
:doc:`../playbooks_filters`
Jinja2 filter plugins
:doc:`../playbooks_tests`
Jinja2 test plugins
:doc:`../playbooks_lookups`
Jinja2 lookup plugins
:doc:`vars`
Ansible vars plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

62
docs/docsite/rst/plugins/inventory.rst Normal file
View file

@ -0,0 +1,62 @@
.. contents:: Topics
Inventory Plugins
-----------------
Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target it's tasks.
They control what happens when with ``-i /path/to/file`` and/or ``-i 'host1, host2`` when passed into Ansible (or from other configuration sources).
.. _enabling_inventory_plugins:
Enabling Inventory Plugins
++++++++++++++++++++++++++
Most inventory plugins shipped with Ansible are disabled by default and need to be whitelisted in your
:doc:`ansible.cfg <../config>` file in order to function. For example, this is how the default looks like:
.. code-block:: ini
[inventory]
enable_plugins = host_list, script, yaml, ini
This list also establishes the order in which each plugin tries to parse an inventory source (in the case 2 plugins can use the same source).
Any plugins left out of the list will not be considered, so you can 'optimize' your inventory loading by minimizing it to what you actually use:
.. code-block:: ini
[inventory]
enable_plugins = advanced_host_list, constructed, yaml
Plugin List
+++++++++++
You can use ``ansible-doc -t inventory -l`` to see the list of available plugins,
use ``ansible-doc -t inventory <plugin name>`` to see specific documents and examples.
.. toctree:: :maxdepth: 1
:glob:
inventory/*
.. seealso::
:doc:`../playbooks`
An introduction to playbooks
:doc:`callback`
Ansible callback plugins
:doc:`connection`
Ansible connection plugins
:doc:`../playbooks_filters`
Jinja2 filter plugins
:doc:`../playbooks_tests`
Jinja2 test plugins
:doc:`../playbooks_lookups`
Jinja2 lookup plugins
:doc:`vars`
Ansible vars plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

36
docs/docsite/rst/plugins/shell.rst Normal file
View file

@ -0,0 +1,36 @@
Shell Plugins
-------------
These plugins work behind the scenes making sure the basic commands Ansible runs,
in order to be able to execute a task's action,
are properly formated to work with the target machine.
You normally don't have to wory about these plugins at all,
unless you have a restricted or exotic setup,
in which the default ``/bin/sh`` is not a POSIX compatible shell or not availble for execution.
Enabling Shell Plugins
++++++++++++++++++++++
You probably never need to do this, but aside from the defaul configuration settings in :doc:`../config`,
you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use,
you will also want to update the :ref:`ansible_executable` to match.
.. seealso::
:doc:`../playbooks`
An introduction to playbooks
:doc:`inventory`
Ansible inventory plugins
:doc:`callback`
Ansible callback plugins
:doc:`../playbooks_filters`
Jinja2 filter plugins
:doc:`../playbooks_tests`
Jinja2 test plugins
:doc:`../playbooks_lookups`
Jinja2 lookup plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

71
docs/docsite/rst/plugins/strategy.rst Normal file
View file

@ -0,0 +1,71 @@
.. contents:: Topics
Strategy Plugins
----------------
Strategy plugins control the flow of play execution, they handle task and host scheduleing.
Enabling Cache 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 :doc:`linear <strategy/linear>` plugin, you can change this default via :doc:`configuration <../config>`:
.. code-block:: shell
export ANSIBLE_STRATEGY=free
or in the `ansible.cfg` file:
.. code-block:: ini
[defaults]
strategy=linear
Or you can just speicfy the plugin in the play via the :ref:`strategy` keyword::
- hosts: all
strategy: debug
tasks:
- copy: src=myhosts dest=/etc/hosts
notify: restart_tomcat
- package: name=tomcat state=present
handlers:
- name: restart_tomcat
service: name=tomcat state=restarted
Plugin List
+++++++++++
You can use ``ansible-doc -t strategy -l`` to see the list of available plugins,
use ``ansible-doc -t strategy <plugin name>`` to see specific documents and examples.
.. toctree:: :maxdepth: 1
:glob:
strategy/*
.. seealso::
:doc:`../playbooks`
An introduction to playbooks
:doc:`inventory`
Ansible inventory plugins
:doc:`callback`
Ansible callback plugins
:doc:`../playbooks_filters`
Jinja2 filter plugins
:doc:`../playbooks_tests`
Jinja2 test plugins
:doc:`../playbooks_lookups`
Jinja2 lookup plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

48
docs/docsite/rst/plugins/vars.rst Normal file
View file

@ -0,0 +1,48 @@
.. contents:: Topics
Vars Plugins
------------
They inject additional variable data into ansible runs that did not come from an inventory source, playbook, or command line.
The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible provides reading variables from :ref:`host_vars` and :ref:`group_vars`.
Enabling Vars Plugins
+++++++++++++++++++++
You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play or inside a role
or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`.
Plugin Lists
++++++++++++
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 documents and examples.
.. toctree:: :maxdepth: 1
:glob:
vars/*
.. seealso::
:doc:`action`
Ansible Action plugins
:doc:`cache`
Ansible Cache plugins
:doc:`callback`
Ansible callback plugins
:doc:`connection`
Ansible connection plugins
:doc:`inventory`
Ansible inventory plugins
:doc:`shell`
Ansible Shell plugins
:doc:`strategy`
Ansible Strategy plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel