From 2ed46e04f4aacd416deb5a489770f84944906a37 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 11 Oct 2017 00:15:25 -0400 Subject: [PATCH] more updates to plugin/config generation (#30787) * fixed module generation added missing lookup page point to plugins when plugins made modules singular add display for verbose an debug messages nicer templating, changed generation order for ref corrected links moved most of lookup docs to plugin section * Copy edits * Fixed typos * Clarified wording --- docs/bin/plugin_formatter.py | 162 +++++++++--------- docs/docsite/Makefile | 2 +- docs/docsite/rst/playbooks_lookups.rst | 7 +- docs/docsite/rst/plugins/action.rst | 9 + docs/docsite/rst/plugins/cache.rst | 18 +- docs/docsite/rst/plugins/callback.rst | 2 + docs/docsite/rst/plugins/connection.rst | 49 +++--- docs/docsite/rst/plugins/inventory.rst | 15 +- docs/docsite/rst/plugins/lookup.rst | 99 +++++++++++ docs/docsite/rst/plugins/shell.rst | 20 ++- docs/docsite/rst/plugins/strategy.rst | 13 +- docs/docsite/rst/plugins/vars.rst | 13 ++ docs/templates/config.rst.j2 | 2 +- .../templates/list_of_CATEGORY_modules.rst.j2 | 2 +- docs/templates/plugin.rst.j2 | 65 +++++-- lib/ansible/plugins/inventory/openstack.py | 3 + 16 files changed, 345 insertions(+), 136 deletions(-) create mode 100644 docs/docsite/rst/plugins/lookup.rst diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index cafc818e34..d50cd9806d 100755 --- a/docs/bin/plugin_formatter.py +++ b/docs/bin/plugin_formatter.py @@ -26,7 +26,7 @@ import datetime import glob import optparse import os -import pprint +from pprint import PrettyPrinter import re import sys import warnings @@ -47,6 +47,7 @@ from six import iteritems, string_types from ansible.errors import AnsibleError from ansible.module_utils._text import to_bytes from ansible.utils import plugin_docs +from ansible.utils.display import Display ##################################################################################### @@ -74,6 +75,9 @@ _CONST = re.compile(r"C\(([^)]+)\)") DEPRECATED = b" (D)" +pp = PrettyPrinter() +display = Display() + def rst_ify(text): ''' convert symbols like I(this is in italics) to valid restructured text ''' @@ -132,13 +136,13 @@ def write_data(text, output_dir, outputname, module=None): print(text) -def get_module_info(module_dir, limit_to_modules=None, verbose=False): +def get_plugin_info(module_dir, limit_to=None, verbose=False): ''' - Returns information about modules and the categories that they belong to + Returns information about plugins and the categories that they belong to - :arg module_dir: file system path to the top of the modules directory - :kwarg limit_to_modules: If given, this is a list of module names to - generate information for. All other modules will be ignored. + :arg module_dir: file system path to the top of the plugin directory + :kwarg limit_to: If given, this is a list of plugin names to + generate information for. All other plugins will be ignored. :returns: Tuple of two dicts containing module_info, categories, and aliases and a set listing deprecated modules: @@ -184,7 +188,7 @@ def get_module_info(module_dir, limit_to_modules=None, verbose=False): # If requested, limit module documentation building only to passed-in # modules. - if limit_to_modules is not None and module.lower() not in limit_to_modules: + if limit_to is not None and module.lower() not in limit_to: continue deprecated = False @@ -260,15 +264,15 @@ def generate_parser(): p.add_option("-A", "--ansible-version", action="store", dest="ansible_version", default="unknown", help="Ansible version number") p.add_option("-M", "--module-dir", action="store", dest="module_dir", default=MODULEDIR, help="Ansible library path") - p.add_option("-P", "--plugin-type", action="store", dest="plugin_type", default='modules', help="The type of plugin (plugins, modules)") + p.add_option("-P", "--plugin-type", action="store", dest="plugin_type", default='module', help="The type of plugin (module, lookup, etc)") p.add_option("-T", "--template-dir", action="store", dest="template_dir", default="hacking/templates", help="directory containing Jinja2 templates") p.add_option("-t", "--type", action='store', dest='type', choices=['rst'], default='rst', help="Document type") - p.add_option("-v", "--verbose", action='store_true', default=False, help="Verbose") p.add_option("-o", "--output-dir", action="store", dest="output_dir", default=None, help="Output directory for module files") p.add_option("-I", "--includes-file", action="store", dest="includes_file", default=None, help="Create a file containing list of processed modules") - p.add_option("-l", "--limit-to-modules", action="store", dest="limit_to_modules", default=None, - help="Limit building module documentation to comma-separated list of modules. Specify non-existing module name for no modules.") + p.add_option("-l", "--limit-to-modules", '--limit-to', action="store", dest="limit_to", default=None, + help="Limit building module documentation to comma-separated list of plugins. Specify non-existing plugin name for no plugins.") p.add_option('-V', action='version', help='Show version number and exit') + p.add_option('-v', '--verbose', dest='verbosity', default=0, action="count", help="verbose mode (increase number of 'v's for more)") return p @@ -287,11 +291,17 @@ def jinja2_environment(template_dir, typ, plugin_type): env.filters['fmt'] = rst_fmt env.filters['xline'] = rst_xline templates['plugin'] = env.get_template('plugin.rst.j2') - templates['category_list'] = env.get_template('%s_by_category.rst.j2' % plugin_type) - templates['support_list'] = env.get_template('%s_by_support.rst.j2' % plugin_type) - templates['list_of_CATEGORY_modules'] = env.get_template('list_of_CATEGORY_%s.rst.j2' % plugin_type) + + if plugin_type == 'module': + name = 'modules' + else: + name = 'plugins' + + templates['category_list'] = env.get_template('%s_by_category.rst.j2' % name) + templates['support_list'] = env.get_template('%s_by_support.rst.j2' % name) + templates['list_of_CATEGORY_modules'] = env.get_template('list_of_CATEGORY_%s.rst.j2' % name) else: - raise Exception("unknown module format type: %s" % typ) + raise Exception("Unsupported format type: %s" % typ) return templates @@ -309,22 +319,17 @@ 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_plugins(module_map, templates, outputname, output_dir, ansible_version, plugin_type): for module in module_map: - # print("rendering: %s" % module) - - # pprint.pprint(('process_modules module:', module)) + display.display("rendering: %s" % module) fname = module_map[module]['path'] - - # pprint.pprint(('process_modules module_info: ', module_map[module])) - - module_categories = module_map[module].get('categories', []) + display.vvvvv(pp.pformat(('process_plugins info: ', module_map[module]))) # crash if module is missing documentation and not explicitly hidden from docs index if module_map[module]['doc'] is None: - print("%s: ERROR: MODULE MISSING DOCUMENTATION" % (fname,)) - _doc = {'module': module, + display.error("%s MISSING DOCUMENTATION" % (fname,)) + _doc = {plugin_type: module, 'version_added': '2.4', 'filename': fname} module_map[module]['doc'] = _doc @@ -332,8 +337,7 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi # Going to reference this heavily so make a short name to reference it by doc = module_map[module]['doc'] - - # pprint.pprint(('process_modules doc: ', doc)) + display.vvvvv(pp.pformat(('process_plugins doc: ', doc))) # add some defaults for plugins that dont have most of the info doc['module'] = doc.get('module', module) @@ -342,12 +346,12 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi doc['plugin_type'] = plugin_type if module_map[module]['deprecated'] and 'deprecated' not in doc: - print("%s: WARNING: MODULE MISSING DEPRECATION DOCUMENTATION: %s" % (fname, 'deprecated')) + display.warning("%s PLUGIN MISSING DEPRECATION DOCUMENTATION: %s" % (fname, 'deprecated')) required_fields = ('short_description',) for field in required_fields: if field not in doc: - print("%s: WARNING: MODULE MISSING field '%s'" % (fname, field)) + display.warning("%s PLUGIN MISSING field '%s'" % (fname, field)) not_nullable_fields = ('short_description',) for field in not_nullable_fields: @@ -355,8 +359,7 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi print("%s: WARNING: MODULE field '%s' DOCUMENTATION is null/empty value=%s" % (fname, field, doc[field])) if 'version_added' not in doc: - pprint.pprint(doc) - # sys.exit("*** ERROR: missing version_added in: %s ***\n" % module) + display.error("*** ERROR: missing version_added in: %s ***\n" % module) # # The present template gets everything from doc so we spend most of this @@ -424,7 +427,7 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi doc['metadata'] = module_map[module]['metadata'] - # pprint.pprint(module_map[module] + display.vvvvv(pp.pformat(module_map[module])) if module_map[module]['returndocs']: try: doc['returndocs'] = yaml.safe_load(module_map[module]['returndocs']) @@ -438,29 +441,18 @@ def process_modules(module_map, templates, outputname, output_dir, ansible_versi if isinstance(doc['author'], string_types): doc['author'] = [doc['author']] - # print('about to template') - # pprint.pprint(doc) + display.v('about to template %s' % module) + display.vvvvv(pp.pformat(doc)) text = templates['plugin'].render(doc) - - # plugins get namespace dirs but modules do not - if plugin_type == 'plugins': - for module_category in module_categories: - category_output_dir = os.path.join(output_dir, 'plugins', '%s' % module_category) - write_data(text, category_output_dir, outputname, module) - else: - write_data(text, output_dir, outputname, module) + write_data(text, output_dir, outputname, module) -def process_categories(mod_info, categories, templates, - output_dir, output_name, plugin_type): +def process_categories(plugin_info, categories, templates, output_dir, output_name, plugin_type): for category in sorted(categories.keys()): - if (plugin_type, category) == ('plugins', ''): - print('skipping unknown cat: %s' % category) - continue module_map = categories[category] category_filename = output_name % category - print("*** recording category %s in %s ***" % (category, category_filename)) + display.display("*** recording category %s in %s ***" % (category, category_filename)) # start a new category file @@ -472,7 +464,7 @@ def process_categories(mod_info, categories, templates, 'category_name': category_name, 'category': module_map, 'subcategories': subcategories, - 'module_info': mod_info, + 'module_info': plugin_info, 'plugin_type': plugin_type } @@ -480,7 +472,7 @@ def process_categories(mod_info, categories, templates, write_data(text, output_dir, category_filename) -def process_support_levels(mod_info, templates, output_dir, plugin_type): +def process_support_levels(plugin_info, templates, output_dir, plugin_type): supported_by = {'Ansible Core Team': {'slug': 'core_supported', 'modules': [], 'output': 'core_maintained.rst', @@ -528,9 +520,9 @@ These modules are currently shipped with Ansible, but will most likely be shippe if plugin_type == 'plugins': return # Separate the modules by support_level - for module, info in mod_info.items(): + for module, info in plugin_info.items(): if not info.get('metadata', None): - print('no metadata for %s' % module) + display.warning('no metadata for %s' % module) continue if info['metadata']['supported_by'] == 'core': supported_by['Ansible Core Team']['modules'].append(module) @@ -548,7 +540,7 @@ These modules are currently shipped with Ansible, but will most likely be shippe template_data = {'maintainers': maintainers, 'modules': data['modules'], 'slug': data['slug'], - 'module_info': mod_info, + 'module_info': plugin_info, } text = templates['support_list'].render(template_data) write_data(text, output_dir, data['output']) @@ -567,62 +559,72 @@ def validate_options(options): def main(): + # INIT p = generate_parser() - (options, args) = p.parse_args() validate_options(options) - + display.verbosity = options.verbosity plugin_type = options.plugin_type - if plugin_type == 'modules': - templates = jinja2_environment(options.template_dir, options.type, plugin_type) - output_dir = options.output_dir + # prep templating + templates = jinja2_environment(options.template_dir, options.type, plugin_type) + + # set file/directory structure + if plugin_type == 'module': # trim trailing s off of plugin_type for plugin_type=='modules'. ie 'copy_module.rst' - outputname = '%s_' + '%s.rst' % plugin_type[:-1] + outputname = '%s_' + '%s.rst' % plugin_type + output_dir = options.output_dir 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(",")] + display.vv('output name: %s' % outputname) + display.vv('output dir: %s' % output_dir) - mod_info, categories = get_module_info(options.module_dir, limit_to_modules=options.limit_to_modules, verbose=options.verbose) + # Convert passed-in limit_to to None or list of modules. + if options.limit_to is not None: + options.limit_to = [s.lower() for s in options.limit_to.split(",")] - categories['all'] = {'_modules': mod_info.keys()} + plugin_info, categories = get_plugin_info(options.module_dir, limit_to=options.limit_to, verbose=(options.verbosity > 0)) + + categories['all'] = {'_modules': plugin_info.keys()} + + display.vvv(pp.pformat(categories)) + display.vvvvv(pp.pformat(plugin_info)) - # pprint.pprint(categories) - # pprint.pprint(mod_info) - # pprint.pprint(dict(mod_info)) # Transform the data if options.type == 'rst': - for key, record in mod_info.items(): - # pprint.pprint(('record', record)) + display.v('Generating rst') + for key, record in plugin_info.items(): + display.vv(key) + display.vvvvv(pp.pformat(('record', record))) if record.get('doc', None): short_desc = record['doc']['short_description'] if short_desc is None: - print('WARNING: short_description for %s is None' % key) + display.warning('short_description for %s is None' % key) short_desc = '' record['doc']['short_description'] = rst_ify(short_desc) - if plugin_type == 'modules': - # Write master category list + if plugin_type == 'module': + display.v('Generating Categories') + # Write module master category list category_list_text = templates['category_list'].render(categories=sorted(categories.keys())) - category_index_name = '%s_by_category.rst' % plugin_type + category_index_name = '%ss_by_category.rst' % plugin_type write_data(category_list_text, output_dir, category_index_name) - # Render all the individual module pages - process_modules(mod_info, templates, outputname, output_dir, options.ansible_version, plugin_type) + # Render all the individual plugin pages + display.v('Generating plugin pages') + process_plugins(plugin_info, templates, outputname, output_dir, options.ansible_version, plugin_type) # Render all the categories for modules - if plugin_type == 'modules': - category_list_name_template = 'list_of_%s_' + '%s.rst' % plugin_type - process_categories(mod_info, categories, templates, output_dir, category_list_name_template, plugin_type) + if plugin_type == 'module': + display.v('Generating Category lists') + category_list_name_template = 'list_of_%s_' + '%ss.rst' % plugin_type + process_categories(plugin_info, categories, templates, output_dir, category_list_name_template, plugin_type) # Render all the categories for modules - process_support_levels(mod_info, templates, output_dir, plugin_type) + process_support_levels(plugin_info, templates, output_dir, plugin_type) if __name__ == '__main__': diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index eed766e45c..1c5522dda1 100644 --- a/docs/docsite/Makefile +++ b/docs/docsite/Makefile @@ -32,7 +32,7 @@ all: docs docs: clean htmldocs -generate_rst: testing keywords modules plugins staticmin cli config +generate_rst: staticmin config cli keywords modules plugins testing htmldocs: generate_rst CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html diff --git a/docs/docsite/rst/playbooks_lookups.rst b/docs/docsite/rst/playbooks_lookups.rst index 3dce6b2f49..e1e355b9e1 100644 --- a/docs/docsite/rst/playbooks_lookups.rst +++ b/docs/docsite/rst/playbooks_lookups.rst @@ -18,9 +18,8 @@ Lookup plugins allow access to outside data sources. Like all templating, these Lookups and loops ````````````````` -Various *lookup plugins* allow additional ways to iterate over data. -In :doc:`Loops ` you will learn how to use them to walk over collections of numerous types. -However, they can also be used to pull in data from remote sources, such as shell commands or even key value stores. +*lookup plugins* are a way to query external data sources, such as shell commands or even key value stores. + Before Ansible 2.5, lookups were mostly used indirectly in ``with_`. +.. _using_action: + +Using Action Plugins ++++++++++++++++++++++ + +Action plugin are executed by default when an associated module is used; no action is required. + .. seealso:: :doc:`cache` diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index 82eec09271..43ba9b2dfa 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -10,11 +10,12 @@ without the performance hit of retrieving them from source. The default cache plugin is the :doc:`memory ` plugin, which only caches the data for the current execution of Ansible. Other plugins with persistent storage are available to allow caching the data across runs. +.. _enabling_cache: + Enabling Cache Plugins ++++++++++++++++++++++ Only one cache plugin can be active at a time. - You can enable a cache plugin in the Ansible configuration, either via environment variable: .. code-block:: shell @@ -31,10 +32,23 @@ or in the ``ansible.cfg`` file: You will also need to configure other settings specific to each plugin. Consult the individual plugin documentation or the Ansible :doc:`configuration <../config>` for more details. +A custom cache plugin is enabled by dropping it into a ``cache_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`. + + +.. _using_cache: + +Using Cache Plugins ++++++++++++++++++++ + +Cache plugins are used autoamtically once they are enabled. + + +.. _cache_plugin_list: + Plugin List +++++++++++ -You can use ``ansible-doc -t cache -l`` to see the list of available plugins. +You can use ``ansible-doc -t cache -l`` to see the list of available plugins. Use ``ansible-doc -t cache `` to see specific documentation and examples. .. toctree:: :maxdepth: 1 diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 1ab416233a..9e3c295a50 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -70,6 +70,8 @@ You can also set this as an environment variable: export ANSIBLE_LOAD_CALLBACK_PLUGINS=1 +.. _callback_plugin_list: + Plugin List +++++++++++ diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 14f2ffaaf1..8baaa12e77 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -11,7 +11,6 @@ By default, Ansible ships with several plugins. The most commonly used are the ' The basics of these connection types are covered in the :doc:`../intro_getting_started` section. -.. contents:: Topics .. _ssh_plugins: @@ -20,28 +19,7 @@ ssh Plugins Because ssh is the default protocol used in system administration and the protocol most used in Ansible, ssh options are included in the command line tools. 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 ` plugin instead. - -Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory_hostname` and defaults to find the target host. - -Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins: - -: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 ` and :doc:`paramiko ` the default value is 22. -:ref:ansible_user - The default user name to use for log in. Most plugins default to the current user running Ansible. - -Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host` for the :doc:`ssh ` plugin. +.. _enabling_connection: Enabling Connection Plugins +++++++++++++++++++++++++++ @@ -49,6 +27,31 @@ Enabling Connection Plugins You can extend Ansible to support other transports (such as SNMP or message bus) by dropping a custom plugin into the ``connection_plugins`` directory. + +.. _using_connection: + +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 to use the :doc:`winrm ` plugin. + +Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory_hostname` and defaults to find the target host. + +Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins: + +: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 ` and :doc:`paramiko ` it defaults to 22. +:ref:`ansible_user` + The default user name to use for log in. Most plugins default to the 'current user running Ansible'. + +Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host` for the :doc:`ssh ` plugin. + +.. _connection_plugin_list: + Plugin List +++++++++++ diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index b9ed30c70c..588bd1bb2c 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -6,7 +6,8 @@ Inventory Plugins Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either via the ``-i /path/to/file`` and/or ``-i 'host1, host2`` command line parameters or from other configuration sources. -.. _enabling_inventory_plugins: + +.. _enabling_inventory: Enabling Inventory Plugins ++++++++++++++++++++++++++ @@ -28,6 +29,18 @@ This list also establishes the order in which each plugin tries to parse an inve enable_plugins = advanced_host_list, constructed, yaml +.. _using_inventory: + +Using Inventory Plugins ++++++++++++++++++++++++ + +The only requirement for using an inventory plugin after it is enabled is to provide an inventory source to parse. +Ansible will try to use the list of enabled inventory plugins, in order, against each inventory source provided. +Once an inventory plugin succeeds at parsing a source, the any remaining inventory plugins will be skipped for that source. + + +.. _inventory_plugin_list: + Plugin List +++++++++++ diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst new file mode 100644 index 0000000000..691c806ff6 --- /dev/null +++ b/docs/docsite/rst/plugins/lookup.rst @@ -0,0 +1,99 @@ +.. contents:: Topics + + +Lookup Plugins +-------------- + +Lookup plugins allow Ansible to access data from outside sources. +This can include reading the filesystem in addition to contacting external datastores and services. +Like all templating, these plugins are evaluated on the Ansible control machine, not on the target/remote. + +The data returned by a lookup plugin is made available using the standard templating system in Ansible, +and are typically used to load variables or templates with information from those systems. + +Lookups are an Ansible-specific extension to the Jinja2 templating language. + +.. note:: + - Lookups are executed with a working directory relative to the role or play, + as opposed to local tasks, which are executed relative the executed script. + - Since Ansible version 1.9, you can pass wantlist=True to lookups to use in Jinja2 template "for" loops. + - Lookup plugins are an advanced feature; to best leverage them you should have a good working knowledge of how to use Ansible plays. + +.. warning:: + - Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage. + + +.. _enabling_lookup: + +Enabling Lookup Plugins ++++++++++++++++++++++++ + +You can activate a custom lookup by either dropping it into a ``lookup_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the lookup directory sources configured in :doc:`ansible.cfg <../config>`. + + +.. _using_lookup: + +Using Lookup Plugins +++++++++++++++++++++ + +Lookup plugins can be used anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :doc:`template <../template_module>` module. + +.. code-block:: yaml + + vars: + file_contents: "{{lookup('file', 'path/to/file.txt')}}" + +Lookups are an integral part of loops. Wherever you see ``with_``, the part after the underscore is the name of a lookup. +This is also the reason most lookups output lists and take lists as input; for example, ``with_items`` uses the :doc:`items ` lookup: + +.. code-block:: yaml + + tasks: + - name: count to 3 + debug: msg={{item}} + with_items: [1, 2, 3] + +You can combine lookups with :doc:`../playbooks_filters`, :doc:`../playbooks_tests` and even each other to do some complex data generation and maniplulation. For example: + +.. code-block:: yaml + + tasks: + - name: valid but useless and over complicated chained lookups and filters + debug: msg="find the answer here:\n{{ lookup('url', 'http://google.com/search/?q=' + item|urlencode)|join(' ') }}" + with_nested: + - "{{lookup('consul_kv', 'bcs/' + lookup('file', '/the/question') + ', host=localhost, port=2000')|shuffle}}" + - "{{lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list)}}" + - ['a', 'c', 'd', 'c'] + + +.. _lookup_plugins_list: + +Plugin List ++++++++++++ + +You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. Use ``ansible-doc -t lookup `` to see specific documents and examples. + + +.. toctree:: :maxdepth: 1 + :glob: + + lookup/* + +.. 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 `_ + Have a question? Stop by the google group! + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index 56ae0f9ca2..7462a565f0 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/docs/docsite/rst/plugins/shell.rst @@ -1,15 +1,27 @@ Shell Plugins ------------- -Shell plugins work transparently to ensure that the basic commands Ansible runs are properly formated to work with the target machine. +Shell plugins work transparently to ensure that the basic commands Ansible runs are properly formatted to work with the target machine. + +.. _enabling_shell: Enabling Shell Plugins ++++++++++++++++++++++ -.. warning:: These plugins should not be reconfigured 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. +You can add a custom shell plugin by dropping it into a ``shell_plugins`` directory adjacent to your play, inside a role, +or by putting it in one of the shell plugin directory sources configured in :doc:`ansible.cfg <../config>`. -In addition to modifying the default configuration settings in :doc:`../config`, you can use a 'connection variable' :ref:`ansible_shell_type` to select a shell plugin, and update the :ref:`ansible_executable` to match. +.. warning:: You should not alter the configuration for these plugins unless you have a setup + in which the default ``/bin/sh`` is not a POSIX compatible shell or is not availble for execution. + +.. _using_shell: + +Using Shell Plugins ++++++++++++++++++++ + +In addition to the default configuration settings in :doc:`../config`, +you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use. +In this case, you will also want to update the :ref:`ansible_executable` to match. .. seealso:: diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst index 046f050fa7..5e3bb97814 100644 --- a/docs/docsite/rst/plugins/strategy.rst +++ b/docs/docsite/rst/plugins/strategy.rst @@ -6,11 +6,21 @@ Strategy Plugins Strategy plugins control the flow of play execution by handling task and host scheduling. +.. _enable_strategy: Enabling Strategy 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. +Strategy plugins shipped with Ansible are enabled by default. You can enable a custom strategy plugin by +putting it in one of the lookup directory sources configured in :doc:`ansible.cfg <../config>`. + + +.. _using_strategy: + +Using Strategy 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 ` plugin. You can change this default in Ansible :doc:`configuration <../config>` using an environment variable: .. code-block:: shell @@ -38,6 +48,7 @@ You can also specify the strategy plugin in the play via the :ref:`strategy` key - name: restart_tomcat service: name=tomcat state=restarted +.. _strategy_plugin_list: Plugin List +++++++++++ diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst index d1614be83c..a002eff5a1 100644 --- a/docs/docsite/rst/plugins/vars.rst +++ b/docs/docsite/rst/plugins/vars.rst @@ -11,11 +11,24 @@ Vars plugins were partially implented in Ansible 2.0 and rewritten to be fully i The :doc:`host_group_vars ` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`. +.. _enable_vars: + Enabling Vars Plugins +++++++++++++++++++++ You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`. + +.. _using_vars: + +Using Vars Plugins +++++++++++++++++++ + +Vars plugins are used automatically after they are enabled. + + +.. _vars_plugin_list: + Plugin Lists ++++++++++++ diff --git a/docs/templates/config.rst.j2 b/docs/templates/config.rst.j2 index e3ffa531b8..3df3bf0ba6 100644 --- a/docs/templates/config.rst.j2 +++ b/docs/templates/config.rst.j2 @@ -15,7 +15,7 @@ where their current value comes from. See :doc:ansible-config for more informati The configuration file ====================== -Changes can be made and used in a configuration file which will be searched for in the following order:: +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) diff --git a/docs/templates/list_of_CATEGORY_modules.rst.j2 b/docs/templates/list_of_CATEGORY_modules.rst.j2 index 7fcf01f0a9..3323fd5c83 100644 --- a/docs/templates/list_of_CATEGORY_modules.rst.j2 +++ b/docs/templates/list_of_CATEGORY_modules.rst.j2 @@ -1,4 +1,4 @@ -@{ title }@ @{ plugin_type }@ +@{ title }@ @{ plugin_type + 's' }@ @{ '`' * title | length }@```````` {% if blurb %} diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index 392a3911ba..7b1e4163d5 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -58,20 +58,22 @@ Aliases: @{ ','.join(aliases) }@ {% endif %} -{% if requirements %} - -Requirements (on host that executes module) -------------------------------------------- {% if requirements %} +{% set req = 'Requirements' %} +{% if plugin_type == 'module' %} +{% set req = req + ' (on host that executes module)' %} +{% endif %} +{% set req_len = req|length %} +@{ req }@ +@{ '-' * req_len }@ + {% for req in requirements %} * @{ req | convert_symbols_to_format }@ {% endfor %} {% endif %} - -{% endif %} {% if options -%} @@ -87,6 +89,9 @@ Options required default choices +{% if plugin_type != 'module' %} + configuration +{% endif %} comments {% for k in option_keys -%} @@ -102,23 +107,48 @@ Options {% else %} {% if v['choices'] -%}
    {% for choice in v.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
{% endif -%} {% endif %} +{% if plugin_type != 'module' %} + {% if 'ini' in v %} +
ini entries: + {% for ini in v.get('ini') %} +

[@{ ini.section }@ ]
@{ ini.key}@ = @{ v['default']|default('VALUE') }@

+ {% endfor %} +
+ {% endif %} + {% if 'env' in v %} + {% for env in v.get('env') %} +
env:@{ env.name }@
+ {% endfor %} + {% endif %} + {% if 'vars' in v %} + {% for myvar in v.get('vars') %} +
var: @{ myvar.name }@
+ {% endfor %} + {% endif %} + +{% endif %} + {% if v.description is string %}
@{ v.description | replace('\n', '\n ') | html_ify }@
{% else %} {% for desc in v.description %} -
@{ desc | replace('\n', '\n ') | html_ify }@
+

@{ desc | replace('\n', '\n ') | html_ify }@

{% endfor %} {% endif %} {% if 'aliases' in v and v.aliases %}
aliases: @{ v.aliases|join(', ') }@
{% endif %} + + {% else %} - @{ k }@
{% if v['version_added'] -%} (added in @{v['version_added']}@){% endif -%}
{% if v.get('required', False) -%}yes{% else -%}no{% endif -%} +{% if plugin_type != 'module' %} + +{% endif %} {% for desc in v.description %} @@ -187,7 +217,7 @@ Options Examples -------- - :: +.. code-block:: yaml {% for example in examples %} {% if example['description'] %}@{ example['description'] | indent(4, True) }@{% endif %} @@ -203,7 +233,7 @@ Examples Return Values ------------- -Common return values are documented :ref:`here `, the following are the fields unique to this module: +Common return values are documented :ref:`here `, the following are the fields unique to this {{plugin_type}}: .. raw:: html @@ -265,16 +295,12 @@ Common return values are documented :ref:`here `, the foll @{ returndocs[entry].contains[sub].sample }@ {% endfor %} - - - + {% endif %} {% endfor %} - -
-
+

{% endif %} @@ -325,12 +351,13 @@ This module is flagged as **@{cur_state}@** which means that @{module_states[cur Maintenance Info ~~~~~~~~~~~~~~~~ -For more information about Red Hat's this support of this module, please -refer to this `knowledge base article`_ +For more information about Red Hat's this support of this @{ plugin_type }@, +please refer to this `knowledge base article_` {% endif %} {% endif %} {% endif %} -For help in developing on modules, should you be so inclined, please read :doc:`../../community`, :doc:`../../dev_guide/testing` and :doc:`../../dev_guide/developing_modules`. +For help in developing, should you be so inclined, please read :doc:`../../community`, +:doc:`../../dev_guide/testing` and {% if plugin_type == 'module' %}:doc:`../../dev_guide/developing_modules`{% else %}:doc:`../../dev_guide/developing_plugins`{% endif %}. diff --git a/lib/ansible/plugins/inventory/openstack.py b/lib/ansible/plugins/inventory/openstack.py index 0aa59e86c1..fae78185bc 100644 --- a/lib/ansible/plugins/inventory/openstack.py +++ b/lib/ansible/plugins/inventory/openstack.py @@ -11,6 +11,9 @@ __metaclass__ = type DOCUMENTATION = ''' name: openstack plugin_type: inventory + authors: + - Marco Vito Moscaritolo + - Jesse Keating short_description: OpenStack inventory source description: - Get inventory hosts from OpenStack clouds