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
|
||||
-----------------------
|
||||
|
||||
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
|
||||
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
|
||||
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'.
|
||||
|
||||
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:
|
||||
|
||||
|
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
.. _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
|
||||
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.
|
||||
|
||||
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
|
||||
--------------
|
||||
|
||||
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:
|
||||
|
||||
|
@ -68,27 +68,34 @@ Callbacks are one of the more interesting plugin types. Adding additional callb
|
|||
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
|
||||
when playbooks complete.
|
||||
The `log_plays
|
||||
<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
|
||||
to playbook events, and is guaranteed to entertain and/or annoy coworkers.
|
||||
The `osx_say
|
||||
<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
|
||||
+++++++++++
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
.. _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
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
|
||||
|
|
Loading…
Reference in a new issue