mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Merge pull request #5586 from tbielawa/spiff_up_plugins
Spiff up the 'Developing Plugins' page
This commit is contained in:
commit
b8676203b9
1 changed files with 21 additions and 15 deletions
|
@ -14,14 +14,14 @@ as often.
|
||||||
Connection Type Plugins
|
Connection Type Plugins
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection type, and an accelerated connection type named 'fireball' -- there are also some minor players like 'chroot' and 'jail'. All of these can be used
|
By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), 'local' connection type, and an accelerated connection type named 'fireball' (superseded in 1.3 by :doc:`playbooks_acceleration`) -- there are also some minor players like 'chroot' and 'jail'. All of these can be used
|
||||||
in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
|
in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
|
||||||
are covered in the 'getting started' section. Should you want to extend Ansible to support other transports (SNMP? Message bus?
|
are covered in the :doc:`intro_getting_started` section. Should you want to extend Ansible to support other transports (SNMP? Message bus?
|
||||||
Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
|
Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
|
||||||
directory. The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
|
directory. The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
|
||||||
'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later. Previous versions did not support 'smart'.
|
'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later. Previous versions did not support 'smart'.
|
||||||
|
|
||||||
More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/connection_plugins and figure things out pretty easily.
|
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/runner/connection_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/connection_plugins>`_ and figure things out pretty easily.
|
||||||
|
|
||||||
.. _developing_lookup_plugins:
|
.. _developing_lookup_plugins:
|
||||||
|
|
||||||
|
@ -30,7 +30,7 @@ Lookup Plugins
|
||||||
|
|
||||||
Language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins. Just like other plugin types, you can write your own.
|
Language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins. Just like other plugin types, you can write your own.
|
||||||
|
|
||||||
More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/lookup_plugins and figure
|
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/runner/lookup_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/lookup_plugins>`_ and figure
|
||||||
things out pretty easily.
|
things out pretty easily.
|
||||||
|
|
||||||
.. _developing_vars_plugins:
|
.. _developing_vars_plugins:
|
||||||
|
@ -42,7 +42,7 @@ Playbook constructs like 'host_vars' and 'group_vars' work via 'vars' plugins.
|
||||||
data into ansible runs that did not come from an inventory, playbook, or command line. Note that variables
|
data into ansible runs that did not come from an inventory, playbook, or command line. Note that variables
|
||||||
can also be returned from inventory, so in most cases, you won't need to write or understand vars_plugins.
|
can also be returned from inventory, so in most cases, you won't need to write or understand vars_plugins.
|
||||||
|
|
||||||
More documentation on writing connection plugins is pending, though you can jump into lib/ansible/inventory/vars_plugins and figure
|
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/inventory/vars_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/inventory/vars_plugins>`_ and figure
|
||||||
things out pretty easily.
|
things out pretty easily.
|
||||||
|
|
||||||
If you find yourself wanting to write a vars_plugin, it's more likely you should write an inventory script instead.
|
If you find yourself wanting to write a vars_plugin, it's more likely you should write an inventory script instead.
|
||||||
|
@ -52,9 +52,9 @@ If you find yourself wanting to write a vars_plugin, it's more likely you should
|
||||||
Filter Plugins
|
Filter Plugins
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
If you want more Jinja2 filters available in a Jinja2 template (filters like to_yaml and to_json are provided by default), they can be extended by writing a filter plugin. Most of the time, when someone comes up with an idea for a new filter they would like to make available in a playbook, we'll just include them in 'core.py' instead.
|
If you want more Jinja2 filters available in a Jinja2 template (filters like to_yaml and to_json are provided by default), they can be extended by writing a filter plugin. Most of the time, when someone comes up with an idea for a new filter they would like to make available in a playbook, we'll just include them in 'core.py' instead.
|
||||||
|
|
||||||
Jump into lib/ansible/runner/filter_plugins/ for details.
|
Jump into `lib/ansible/runner/filter_plugins/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/filter_plugins>`_ for details.
|
||||||
|
|
||||||
.. _developing_callbacks:
|
.. _developing_callbacks:
|
||||||
|
|
||||||
|
@ -68,27 +68,34 @@ Callbacks are one of the more interesting plugin types. Adding additional callb
|
||||||
Examples
|
Examples
|
||||||
++++++++
|
++++++++
|
||||||
|
|
||||||
Example callbacks are shown `in github in the callbacks directory <https://github.com/ansible/ansible/tree/devel/plugins/callbacks>_`.
|
Example callbacks are shown in `plugins/callbacks <https://github.com/ansible/ansible/tree/devel/plugins/callbacks>`_.
|
||||||
|
|
||||||
The 'log_plays' callback is an example of how to intercept playbook events to a log file, and the 'mail' callback sends email
|
The `log_plays
|
||||||
when playbooks complete.
|
<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/log_plays.py>`_
|
||||||
|
callback is an example of how to intercept playbook events to a log
|
||||||
|
file, and the `mail
|
||||||
|
<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/mail.py>`_
|
||||||
|
callback sends email when playbooks complete.
|
||||||
|
|
||||||
The 'osx_say' callback provided is particularly entertaining -- it will respond with computer synthesized speech on OS X in relation
|
The `osx_say
|
||||||
to playbook events, and is guaranteed to entertain and/or annoy coworkers.
|
<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/osx_say.py>`_
|
||||||
|
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.
|
||||||
|
|
||||||
.. _configuring_callbacks:
|
.. _configuring_callbacks:
|
||||||
|
|
||||||
Configuring
|
Configuring
|
||||||
+++++++++++
|
+++++++++++
|
||||||
|
|
||||||
To active a callback drop it in a callback directory as configured in ansible.cfg.
|
To active a callback drop it in a callback directory as configured in :ref:`ansible.cfg <callback_plugins>`.
|
||||||
|
|
||||||
.. _callback_development:
|
.. _callback_development:
|
||||||
|
|
||||||
Development
|
Development
|
||||||
+++++++++++
|
+++++++++++
|
||||||
|
|
||||||
More information will come later, though see the source of any of the existing callbacks and you should be able to get started quickly.
|
More information will come later, though see the source of any of the existing callbacks and you should be able to get started quickly.
|
||||||
They should be reasonably self explanatory.
|
They should be reasonably self explanatory.
|
||||||
|
|
||||||
.. _distributing_plugins:
|
.. _distributing_plugins:
|
||||||
|
@ -124,4 +131,3 @@ In addition, plugins can be shipped in a subdirectory relative to a top-level pl
|
||||||
The development mailing list
|
The development mailing list
|
||||||
`irc.freenode.net <http://irc.freenode.net>`_
|
`irc.freenode.net <http://irc.freenode.net>`_
|
||||||
#ansible IRC chat channel
|
#ansible IRC chat channel
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue