Introduction #
This is a how-to guide for writing code to extend Ansible beyond the capabilities it ships with in the box.
What might you want to build as extensions? #
- Actions/tasks: plugin, module
- Cache: plugin
- Callbacks: plugin
- Connection: plugin
- Filter: plugins
- Inventory: plugin, external script
- Lookup: plugin
- Test: plugin
- Vars: plugin
Action/task modules and plugins #
Action plugins run on the Ansible controller and have access to Ansible variables.
Task modules, often just called “modules” even though that is somewhat inconsistent, run on the remote host and do not have access to Ansible variables.
You can combine the two in order to get the features of both.
If you aren’t sure which you need, a task module is a good place to start.
Filters plugins #
A filter can transform data in the Jinja2 templating engine that Ansible uses.
Inventory scripts and plugins #
In Ansible, inventories define hosts, place those hosts into groups, and assign host- or group- level variables.
Ansible ships with support for flat-file inventories, and can be extended with simple inventory scripts or more complex inventory plugins depending on your needs.
TODO
Add inventory section
Cache plugins #
TODO
cache prose
Callback plugins #
Callback plugins perform actions during an Ansible run. They are commonly used to implement support for logging to third-party log management systems like Splunk.
TODO
callbacks prose
Connection plugins #
Connection plugins support new types of target hosts to configure. For instance, some network switches have shells that are not POSIX compliant or do not have Python available, so a custom plugin must be written to support them.
TODO
connection prose
Lookup plugins #
Lookup plugins can get data from a database or other external source for use in an Ansible play. They run only on the Ansible controller.
Test plugins #
TODO
Test prose
Vars plugins #
TODO
vars prose
Scenarios #
We also explore some specific scenarios at the end of the cookbook. These might not involve Ansible extensions, but will describe approaches to problems you might encounter.