ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

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
parent 7a312b6cf7
commit b233f3f296
23 changed files with 873 additions and 1360 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
.gitignore vendored
View file

@ -27,28 +27,30 @@ docs/man/man3/*
*.sublime-project
*.sublime-workspace
# docsite stuff...
docs/api/_build/
docs/api/rst/
docs/docsite/*.html
docs/docsite/_build
docs/docsite/_static/*.gif
docs/docsite/_static/*.png
docs/docsite/_static/websupport.js
docs/docsite/htmlout
docs/docsite/searchindex.js
docs/docsite/rst_warnings
docs/docsite/rst/*_module.rst
docs/docsite/rst/ansible.rst
docs/docsite/rst/ansible-*.rst
docs/docsite/rst/community_maintained.rst
docs/docsite/rst/config.rst
docs/docsite/rst/core_maintained.rst
docs/docsite/rst/list_of_*.rst
docs/docsite/rst/*_module.rst
docs/docsite/rst/modules_by_category.rst
docs/docsite/rst/plugins_by_category.rst
docs/docsite/rst/network_maintained.rst
docs/docsite/rst/plugins_by_category.rst
docs/docsite/rst/partner_maintained.rst
docs/docsite/rst/playbook_keywords.rst
docs/docsite/rst/playbooks_directives.rst
docs/docsite/rst/plugins/
docs/docsite/*.html
docs/docsite/_static/*.gif
docs/docsite/_static/*.png
docs/docsite/_static/websupport.js
docs/docsite/searchindex.js
docs/docsite/htmlout
docs/docsite/_build
docs/docsite/rst_warnings
docs/api/rst/
docs/api/_build/
docs/docsite/rst/plugins/*/*.rst
# deb building stuff...
/debian/
deb-build

33
docs/bin/plugin_formatter.py
View file

@ -179,7 +179,7 @@ def get_module_info(module_dir, limit_to_modules=None, verbose=False):
# Do not list blacklisted modules
module = os.path.splitext(os.path.basename(module_path))[0]
if module in plugin_docs.BLACKLIST['MODULE']:
if module in plugin_docs.BLACKLIST['MODULE'] or module == 'base':
continue
# If requested, limit module documentation building only to passed-in
@ -309,8 +309,7 @@ def too_old(added):
return added_float < TO_OLD_TO_BE_NOTABLE
def process_modules(module_map, templates, outputname,
output_dir, ansible_version, plugin_type):
def process_modules(module_map, templates, outputname, output_dir, ansible_version, plugin_type):
for module in module_map:
# print("rendering: %s" % module)
@ -574,21 +573,23 @@ def main():
validate_options(options)
plugin_type = options.plugin_type
templates = jinja2_environment(options.template_dir, options.type,
plugin_type)
# for plugins, just use the short name 'ssh.rst' vs 'ssh_module.rst'
outputname = '%s.rst'
# trim trailing s off of plugin_type for plugin_type=='modules'. ie 'copy_module.rst'
if plugin_type == 'modules':
templates = jinja2_environment(options.template_dir, options.type, plugin_type)
output_dir = options.output_dir
# trim trailing s off of plugin_type for plugin_type=='modules'. ie 'copy_module.rst'
outputname = '%s_' + '%s.rst' % plugin_type[:-1]
else:
templates = jinja2_environment(options.template_dir, options.type, 'plugins')
# for plugins, just use 'ssh.rst' vs 'ssh_module.rst'
outputname = '%s.rst'
output_dir = '%s/plugins/%s' % (options.output_dir, plugin_type)
# Convert passed-in limit_to_modules to None or list of modules.
if options.limit_to_modules is not None:
options.limit_to_modules = [s.lower() for s in options.limit_to_modules.split(",")]
mod_info, categories = get_module_info(options.module_dir, limit_to_modules=options.limit_to_modules,
verbose=options.verbose)
mod_info, categories = get_module_info(options.module_dir, limit_to_modules=options.limit_to_modules, verbose=options.verbose)
categories['all'] = {'_modules': mod_info.keys()}
@ -606,22 +607,22 @@ def main():
short_desc = ''
record['doc']['short_description'] = rst_ify(short_desc)
if plugin_type == 'module':
# Write master category list
category_list_text = templates['category_list'].render(categories=sorted(categories.keys()))
category_index_name = '%s_by_category.rst' % plugin_type
write_data(category_list_text, options.output_dir, category_index_name)
write_data(category_list_text, output_dir, category_index_name)
# Render all the individual module pages
process_modules(mod_info, templates, outputname,
options.output_dir, options.ansible_version, plugin_type)
process_modules(mod_info, templates, outputname, output_dir, options.ansible_version, plugin_type)
# Render all the categories for modules
if plugin_type == 'module':
category_list_name_template = 'list_of_%s_' + '%s.rst' % plugin_type
process_categories(mod_info, categories, templates, options.output_dir,
category_list_name_template, plugin_type)
process_categories(mod_info, categories, templates, output_dir, category_list_name_template, plugin_type)
# Render all the categories for modules
process_support_levels(mod_info, templates, options.output_dir, plugin_type)
process_support_levels(mod_info, templates, output_dir, plugin_type)
if __name__ == '__main__':

11
docs/docsite/Makefile
View file

@ -21,6 +21,8 @@ ifdef PLUGINS
PLUGIN_ARGS = -l $(PLUGINS)
endif
DOC_PLUGINS ?= cache callback connection inventory lookup strategy vars
assertrst:
ifndef rst
$(error specify document or pattern with rst=somefile.rst)
@ -59,10 +61,11 @@ clean:
-rm rst/*_by_category.rst
-rm rst/*_module.rst
-rm rst/*_plugin.rst
-rm -rf rst/plugins/*
-rm rst/*_maintained.rst
-rm rst/playbooks_directives.rst
-rm rst/playbooks_keywords.rst
-rm rst/plugins/*/*.rst
-rm rst/config.rst
-rm rst/ansible-*.rst
-rm rst/ansible.rst
@ -82,7 +85,11 @@ modules: $(FORMATTER) ../templates/plugin.rst.j2
PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/ $(MODULE_ARGS)
plugins: $(FORMATTER) ../templates/plugin.rst.j2
PYTHONPATH=../../lib $(FORMATTER) -t rst --plugin-type plugins --template-dir=../templates --module-dir=../../lib/ansible/plugins -o rst/ $(PLUGIN_ARGS)
@echo "looping over doc plugins"
for plugin in $(DOC_PLUGINS); \
do \
PYTHONPATH=../../lib $(FORMATTER) -t rst --plugin-type $$plugin --template-dir=../templates --module-dir=../../lib/ansible/plugins/$$plugin -o rst/ $(PLUGIN_ARGS); \
done
testing:
$(TESTING_FORMATTER)

12
docs/docsite/rst/command_line_tools.rst
View file

@ -1,15 +1,11 @@
Command Line Tools
==================
Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides.
Below you have the complate list, each page has the detailed swtiches and options that each tool supports and a short description of their purpose.
.. toctree:: :maxdepth: 1
:glob:
ansible
ansible-playbook
ansible-vault
ansible-galaxy
ansible-console
ansible-config
ansible-doc
ansible-inventory
ansible-pull
ansible-*

279
docs/docsite/rst/dev_guide/developing_plugins.rst
View file

@ -4,99 +4,107 @@ Developing Plugins
.. contents:: Topics
Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own.
The following types of plugins are available:
- *Action* plugins are front ends to modules and can execute actions on the controller before calling the modules themselves.
- *Cache* plugins are used to keep a cache of 'facts' to avoid costly fact-gathering operations.
- *Callback* plugins enable you to hook into Ansible events for display or logging purposes.
- *Connection* plugins define how to communicate with inventory hosts.
- *Filters* plugins allow you to manipulate data inside Ansible plays and/or templates. This is a Jinja2 feature; Ansible ships extra filter plugins.
- *Lookup* plugins are used to pull data from an external source. These are implemented using a custom Jinja2 function.
- *Strategy* plugins control the flow of a play and execution logic.
- *Shell* plugins deal with low-level commands and formatting for the different shells Ansible can encounter on remote hosts.
- *Test* plugins allow you to validate data inside Ansible plays and/or templates. This is a Jinja2 feature; Ansible ships extra test plugins.
- *Vars* plugins inject additional variable data into Ansible runs that did not come from an inventory, playbook, or the command line.
This section describes the various types of plugins and how to implement them.
.. _plugin_guidelines:
General Guidelines
------------------
Some things that should apply to any type of plugin you develop.
Raising Errors
``````````````
In general, errors encountered during execution should be returned by raising AnsibleError() or similar class with a message describing the error.
When wrapping other exceptions into error messages you should always use the `to_text` Ansible function to ensure proper string compatiblity across
Python versions:
.. code-block:: python
from ansible.module_utils._text import to_native
try:
cause_an_exeption()
except Exception as e:
AnsibleError('Something happend, this was original exception: %s' % to_native(e))
Check the different AnsibleError objects and see which one applies the best to your situation.
String encoding
```````````````
Any strings returned by your plugin that could ever contain non-ASCII characters must be converted into Python's unicode type
because the strings will be run through jinja2. To do this, you can use:
.. code-block:: python
from ansible.module_utils._text import to_text
result_string = to_text(result_string)
Plugin configuration
````````````````````
Starting in 2.4 and going forward, we are unifying how each plugin type is configured and how they get those settings, plugins will be able to 'declare'
their needs and have Ansible provide them with the 'resolved' configuration. As of 2.4 both Callback and Connection type plugins can use this system,
most plugins will be able to use `self._options[<optionname>]` to access the settings, except callbacks that due to prexisting collsion
use `self._plugin_optoins[<optionname>]`.
Plugins that supprot docs (see `ansible-doc` for the list) are now required to provide documentation to be considered for merge into the Ansible repo.
Also be aware that if you inherit from a plugin you must ALSO document the optoins it takes, either via a documentation fragment or as a copy.
.. _developing_callbacks:
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.
See :doc: plugins/callback as to what they are and how to use them. This section explains how to use them.
.. _callback_examples:
Example Callback Plugins
++++++++++++++++++++++++
Ansible comes with a number of callback plugins that you can look at for examples. These can be found in `lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_.
The `log_plays
<https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/callback/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/lib/ansible/plugins/callback/mail.py>`_
callback sends email when playbooks complete.
The `osx_say
<https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/callback/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 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 `ansible.cfg`.
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 `ansible.cfg` file in order to function. For example::
#callback_whitelist = timer, mail, mycallbackplugin
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 `ansible.cfg`. For example::
#stdout_callback = mycallbackplugin
.. _callback_development:
Developing Callback Plugins
+++++++++++++++++++++++++++
Callback plugins are created by creating a new class with the Base(Callbacks) class as the parent:
.. code-block:: python
from ansible.plugins.callback import CallbackBase
from ansible import constants as C
class CallbackModule(CallbackBase):
pass
From there, override the specific methods from the CallbackBase that you want to provide a callback for. For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with `v2`. For a complete list of methods that you can override, please see ``__init__.py`` in the `lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory.
From there, override the specific methods from the CallbackBase that you want to provide a callback for.
For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with `v2`.
For a complete list of methods that you can override, please see ``__init__.py`` in the
`lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory.
The following example shows how Ansible's timer plugin is implemented:
The following example shows a modified example Ansible's timer plugin is implemented,
but with an extra option so you can see how configuration works in Ansible >= 2.4:
.. code-block:: python
# Make coding more python3-ish
# Make coding more python3-ish, this is required for contributions to Ansible
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
# not only visible to ansible-doc, it also 'declares' the options the plugin requires and how to configure them.
DOCUMENTATION = '''
callback: timer
callback_type: aggregate
requirements:
- whitelist in configuration
short_description: Adds time to play stats
version_added: "2.0"
description:
- This callback just adds total play duration to the play stats.
options:
format_string:
description: format of the string shown to user at play end
ini:
- section: callback_timer
key: format_string
env:
- name: ANSIBLE_CALLBACK_TIMER_FORMAT
default: "Playbook run took %s days, %s hours, %s minutes, %s seconds"
'''
from datetime import datetime
from ansible.plugins.callback import CallbackBase
@ -109,28 +117,35 @@ The following example shows how Ansible's timer plugin is implemented:
CALLBACK_VERSION = 2.0
CALLBACK_TYPE = 'aggregate'
CALLBACK_NAME = 'timer'
# only needed if you ship it and dont want to enable by default
CALLBACK_NEEDS_WHITELIST = True
def __init__(self):
# make sure the expected objects are present, calling the base's __init__
super(CallbackModule, self).__init__()
# start the timer when the plugin is loaded, the first play should start a few miliseconds after.
self.start_time = datetime.now()
def days_hours_minutes_seconds(self, runtime):
def _days_hours_minutes_seconds(self, runtime):
''' internal helper method for this callback '''
minutes = (runtime.seconds // 60) % 60
r_seconds = runtime.seconds - (minutes * 60)
return runtime.days, runtime.seconds // 3600, minutes, r_seconds
def playbook_on_stats(self, stats):
self.v2_playbook_on_stats(stats)
# this is only event we care about for display, when the play shows it's summary stats, the rest are ignored by the base class
def v2_playbook_on_stats(self, stats):
end_time = datetime.now()
runtime = end_time - self.start_time
self._display.display("Playbook run took %s days, %s hours, %s minutes, %s seconds" % (self.days_hours_minutes_seconds(runtime)))
# Shows the usage of a config option declared in the DOCUMENTATION variable, Ansible will have set it when it loads the plugin.
# Also note the use of the display object to print to screen, available to all callbacks, you should prefer this over printing yoruself
self._display.display(self._plugin_options['format_string'] % (self._days_hours_minutes_seconds(runtime)))
Note that the CALLBACK_VERSION and CALLBACK_NAME definitions are required for properly functioning plugins for Ansible >=2.0.
CALLBACK_TYPE is mostly needed to distinguish 'stout' plugins from the rest, as you can only load one of that type.
.. _developing_connection_plugins:
@ -142,7 +157,45 @@ are covered in the :doc:`../intro_getting_started` section. Should you want to
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 and later. Previous versions did not support 'smart'.
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/plugins/connection <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_ and figure things out pretty easily.
More documentation on writing connection plugins is pending, though you can jump into
`lib/ansible/plugins/connection <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_ and figure things out pretty easily.
.. _developing_inventory_plugins:
Inventory Plugins
-----------------
Added in Ansible 2.4 they are in charge of parsing inventory sources and forming the 'in memory' representation of the Inventory.
They are invoked via the InventoryManager and are given access to any existing inventory data added previouslly,
they are given an 'inventory source' as supplied to Ansible (via config/optoins/defaults/etc), which they can ignore
(return false from the `verify_file` method), or attempt to parse (via `parse` method) and return an `AnsibleParserError` on failure.
.. code-block:: python
def parse(self, inventory, loader, path, cache=True):
pass # your code goes here
The parameters are:
* inventory: inventory object with existing data and the methods to add hosts/groups/variables to inventory
* loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh.
* path: string with inventory source (normally a path, but not required)
* cache: hint to the plugin if it should use or avoid caches (Cache plugin and/or loader)
Inventory sources are strings, most of the time they correspond to a file path, but can also be a comma separated list,
a uri or anything your plugin can use as input.
The 'inventory source' provided can be either a string (`host_list` plugin), a data file (like consumed by the `yaml` and `ini` plugins),
a configuration file (see `virtualbox` and `constructed`) or even a script or executable (the `script` uses those) which is how 'inventory scripts' work.
Inventory plugins can also use the configured Cache plugin to store and retrieve data to avoid costly external calls,
of course this only works if using a 'persistent' cache (i.e not the memory one).
Be aware that inventory plugins normally only execute at the start of the run, before playbooks/plays and roles are found,
but they can be 're-executed' via the `meta: refresh_inventory` task, which will clear out the existing inventory and rebuild it.
More documentation on writing inventory plugins is pending, though you can jump into
`lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_ and figure things out pretty easily.
.. _developing_lookup_plugins:
@ -155,6 +208,25 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
.. code-block:: python
# python 3ish headers, required if submitting to Ansible
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
lookup: file
author: Daniel Hokka Zakrisson <daniel@hozac.com>
version_added: "0.9"
short_description: read file contents
description:
- This lookup returns the contents from a file on the Ansible controller's file system.
options:
_terms:
description: path(s) of files to read
required: True
notes:
- if read in variable context, the file can be interpreted as YAML if the content is valid to the parser.
- this lookup does not understand 'globing', use the fileglob lookup instead.
"""
from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.lookup import LookupBase
@ -169,19 +241,28 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
def run(self, terms, variables=None, **kwargs):
ret = []
# lookups in general are expected to both take a list as input and output a list
# this is done so they work with the looping construct `with_`.
ret = []
for term in terms:
display.debug("File lookup term: %s" % term)
# Find the file in the expected search path
# Find the file in the expected search path, using a class method
# that implements the 'expected' search path for Ansible plugins.
lookupfile = self.find_file_in_search_path(variables, 'files', term)
# Don't use print or your own logging, the display class
# takes care of it in a unified way.
display.vvvv(u"File lookup using %s as file" % lookupfile)
try:
if lookupfile:
contents, show_data = self._loader._get_file_contents(lookupfile)
ret.append(contents.rstrip())
else:
# Always use ansible error classes to throw 'final' exceptions,
# so the Ansible engine will know how to deal with them.
# The Parser error indicates invalid options passed
raise AnsibleParserError()
except AnsibleParserError:
raise AnsibleError("could not locate file in lookup: %s" % term)
@ -199,13 +280,6 @@ An example of how this lookup is called::
- debug: msg="the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }}"
Errors encountered during execution should be returned by raising AnsibleError() with a message describing the error. Any strings returned by your lookup plugin implementation that could ever contain non-ASCII characters must be converted into Python's unicode type because the strings will be run through jinja2. To do this, you can use:
.. code-block:: python
from ansible.module_utils._text import to_text
result_string = to_text(result_string)
For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
For usage examples of lookup plugins, see `Using Lookups <http://docs.ansible.com/ansible/playbooks_lookups.html>`_.
@ -215,14 +289,42 @@ For usage examples of lookup plugins, see `Using Lookups <http://docs.ansible.co
Vars Plugins
------------
Playbook constructs like 'host_vars' and 'group_vars' work via 'vars' plugins. They inject additional variable
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.
Playbook constructs like 'host_vars' and 'group_vars' work via 'vars' plugins.
They inject additional variable data into ansible runs that did not come from an inventory source, playbook, or command line.
More documentation on writing vars plugins is pending, though you can jump into `lib/ansible/plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/>`_ and figure
things out pretty easily.
Vars plugins got rewritten in 2.4 and had been semi-functional since 2.0.
Older pugins used a `run` method as their main body/work:
.. code-block:: python
def run(self, name, vault_password=None):
pass # your code goes here
But Ansible 2.0 did not pass passwords to them so vaults were unavilable.
Most of the work now happens in the `get_vars` method which is called from the VariableManager when needed.
.. code-block:: python
def get_vars(self, loader, path, entities):
pass # your code goes here
The parameters are:
* loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh.
* path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data
in reference to them, `get_vars` will be called at least once per available path.
* entities: these are host or group names that are pertinent to the variables needed, the plugin will get called once for hosts and again for groups.
This method just needs to return a dictionary structure with the pertinent variables.
Since Ansible 2.4, vars plugins execute as needed when preparing to execute a task, this avoids the costly 'always execute' that used
to happend during inventory construction.
More documentation on writing vars plugins is pending, though you can jump into
`lib/ansible/plugins/vars <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_ 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.
.. _developing_filter_plugins:
@ -255,11 +357,14 @@ Plugins are automatically loaded when you have one of the following subfolders a
* lookup_plugins
* callback_plugins
* connection_plugins
* inventory_plugins
* filter_plugins
* strategy_plugins
* cache_plugins
* test_plugins
* shell_plugins
* vars_plugins
When shipped as part of a role, the plugin will be available as soon as the role is called in the play.

2
docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst
View file

@ -1,4 +1,4 @@
Sanity Tests » ansible-var-precedence-check
===========================================
Check the order of precedence for Ansible variables against :ref:`variable_precedence`.
Check the order of precedence for Ansible variables against :ref:`ansible_variable_precedence`.

1253
docs/docsite/rst/intro_configuration.rst
View file

File diff suppressed because it is too large Load diff

14
docs/docsite/rst/playbooks_lookups.rst
View file

@ -3,15 +3,15 @@ Lookups
Lookup plugins allow access of data in Ansible from outside sources. Like all templating, these plugins are evaluated on the Ansible control
machine, and can include reading the filesystem but also contacting external datastores and services.
These values are then made available using the standard templating system in Ansible, and are typically used to load variables or templates with information from those systems.
.. note:: This is considered an advanced feature, and many users will probably not rely on these features.
These values are then made available using the standard templating system in Ansible,
and are typically used to load variables or templates with information from those systems.
.. note:: Lookups occur on the local computer, not on the remote computer.
.. note:: Lookups are executed with a cwd relative to the role or play, as opposed to local tasks which are executed with the cwd of the executed script.
.. note:: Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
.. note::
- Lookups occur on the local computer, not on the remote computer.
- They are executed with a cwd relative to the role or play, as opposed to local tasks which are executed with the cwd of the executed script.
- Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
- This is considered an advanced feature, you should try to feel comfortable with Ansible plays before incorporating them.
.. warning:: Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage.

2
docs/docsite/rst/playbooks_reuse_includes.rst
View file

@ -69,7 +69,7 @@ Variables can also be passed to include files using an alternative syntax, which
- "{{ lookup('file', 'keys/one.pub') }}"
- "{{ lookup('file', 'keys/two.pub') }}"
Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :ref:`variable_precedence` for more details on variable inheritance and precedence.
Using either syntax, variables passed in can then be used in the included files. These variables will only be available to tasks within the included file. See :ref:`ansible_variable_precedence` for more details on variable inheritance and precedence.
Task include statements can be used at arbitrary depth.

3
docs/docsite/rst/playbooks_special_topics.rst
View file

@ -16,9 +16,10 @@ and adopt these only if they seem relevant or useful to your environment.
playbooks_environment
playbooks_error_handling
playbooks_advanced_syntax
playbooks_lookups
plugins
playbooks_prompts
playbooks_tags
playbooks_vault
playbooks_startnstep
playbooks_keywords
playbooks_lookups

2
docs/docsite/rst/playbooks_variables.rst
View file

@ -798,7 +798,7 @@ As of Ansible 1.3, extra vars can be loaded from a JSON file with the ``@`` synt
Also as of Ansible 1.3, extra vars can be formatted as YAML, either on the command line
or in a file as above.
.. _variable_precedence:
.. _ansible_variable_precedence:
Variable Precedence: Where Should I Put A Variable?
````````````````````````````````````````````````````

31
docs/docsite/rst/plugins.rst Normal file
View file

@ -0,0 +1,31 @@
Plugins
=======
Ansible uses a plugin architecture to enable a rich, flexible and expandible feature set.
They are pieces of code that augment Ansible's core functionality.
Ansible ships with a number of handy plugins, and you can easily write your own.
There are many types of plugins, these are the most relevant ones:
.. toctree:: :maxdepth: 1
:glob:
plugins/*
playbooks_filters
playbooks_tests
Most of the time you are using them without having to know about them, but when you want to change certain behaviours you need to know how to enable,
activate or trigger each type.
.. seealso::
:doc:`playbooks`
An introduction to playbooks
:doc:`config`
Ansible configuration documentation and settings
:doc:`command_line_tools`
Ansible tools, description and options
`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/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

33
docs/templates/config.rst.j2 vendored
View file

@ -6,9 +6,42 @@
{{name}}
{{ '=' * name_len }}
Ansible supports a few ways of providing configuration variables, mainly through environment variables, command line switches and an ini file `ansible.cfg`.
Starting at Ansible 2.4 the `ansible-config` utility allows users to see all the configuration settings available, their defaults, how to set them and
where their current value comes from. See :doc:ansible-config for more information.
The configuration file
======================
Changes can be made and used in a configuration file which will be searched for in the following order::
* ANSIBLE_CONFIG (environment variable if set)
* ansible.cfg (in the current directory)
* ~/.ansible.cfg (in the home directory)
* /etc/ansible/ansible.cfg
Ansible will process the above list and use the first file found, all others are ignored.
.. note:: Comments
The configuration file is one variant of an INI format.
Both the hash sign ("#") and semicolon (";") are allowed as
comment markers when the comment starts the line.
However, if the comment is inline with regular values,
only the semicolon is allowed to introduce the comment.
For instance::
# some basic default values...
inventory = /etc/ansible/hosts ; This points to the file that lists your hosts
Common Options
==============
This is a copy of the options available from our release, your local install might have extra options due to additional plugins,
you can use the command line utility mentioned above (`ansible-config`) to browse through those.
{% if config_options %}

1
docs/templates/man.j2 vendored
View file

@ -104,7 +104,6 @@ AUTHOR
------
Ansible was originally written by Michael DeHaan.
See the AUTHORS file for a complete list of contributors.
COPYRIGHT

11
lib/ansible/plugins/inventory/constructed.py
View file

@ -13,17 +13,22 @@ DOCUMENTATION = '''
- Uses a YAML configuration file to define var expresisions and group conditionals
- The Jinja2 conditionals that qualify a host for membership.
- The JInja2 exprpessions are calculated and assigned to the variables
- Only variables already available from previous inventories can be used for templating.
- Failed expressions will be ignored (assumes vars were missing).
- Only variables already available from previous inventories or the fact cache can be used for templating.
- When `strict` is False, failed expressions will be ignored (assumes vars were missing).
extends_documentation_fragment:
- constructed
'''
EXAMPLES = '''
# inventory.config file in YAML format
plugin: comstructed
plugin: constructed
strict: False
compose:
var_sum: var1 + var2
# this variable will only be set if I have a persistent fact cache enabled (and have non expired facts)
# `strict: False` will skip this instead of producing an error if it is missing facts.
server_type: "ansible_hostname | regex_replace ('(.{6})(.{2}).*', '\\2')"
groups:
# simple name matching
webservers: inventory_hostname.startswith('web')