mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
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
This commit is contained in:
Brian Coca
GitHub
parent
3886f80e44
commit
2ed46e04f4
16 changed files with 345 additions and 136 deletions
|
|
@ -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__':
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <playbooks_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_<lookup`` constructes for looping, begining in 2.5
|
||||
we use them more explicitly as part of Jinja2 expressions fed into the ``loop`` keyword.
|
||||
|
||||
|
|
@ -37,6 +36,8 @@ One way of using lookups is to populate variables. These macros are evaluated ea
|
|||
tasks:
|
||||
- debug: msg="motd value is {{ motd_value }}"
|
||||
|
||||
For more details and a complete list of lookup plugins available, please see :doc:`plugins/lookup`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
|
|
|
|||
|
|
@ -6,11 +6,20 @@ They usually execute automatically in the background doing prerequisite work bef
|
|||
|
||||
The 'normal' action plugin is used for modules that do not already have an action plugin.
|
||||
|
||||
.. _enabling_action:
|
||||
|
||||
Enabling Action Plugins
|
||||
+++++++++++++++++++++++
|
||||
|
||||
You can enable a custom action plugin by either dropping it into the ``action_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
|
||||
|
||||
.. _using_action:
|
||||
|
||||
Using Action Plugins
|
||||
+++++++++++++++++++++
|
||||
|
||||
Action plugin are executed by default when an associated module is used; no action is required.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`cache`
|
||||
|
|
|
|||
|
|
@ -10,11 +10,12 @@ without the performance hit of retrieving them from source.
|
|||
The default cache plugin is the :doc:`memory <cache/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 <plugin name>`` to see specific documentation and examples.
|
||||
|
||||
.. toctree:: :maxdepth: 1
|
||||
|
|
|
|||
|
|
@ -70,6 +70,8 @@ You can also set this as an environment variable:
|
|||
export ANSIBLE_LOAD_CALLBACK_PLUGINS=1
|
||||
|
||||
|
||||
.. _callback_plugin_list:
|
||||
|
||||
Plugin List
|
||||
+++++++++++
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <connection/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 <connection/ssh>` and :doc:`paramiko <connection/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 <connection/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 <connection/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 <connection/ssh>` and :doc:`paramiko <connection/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 <connection/ssh>` plugin.
|
||||
|
||||
.. _connection_plugin_list:
|
||||
|
||||
Plugin List
|
||||
+++++++++++
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
+++++++++++
|
||||
|
||||
|
|
|
|||
99
docs/docsite/rst/plugins/lookup.rst
Normal file
99
docs/docsite/rst/plugins/lookup.rst
Normal file
|
|
@ -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/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 <plugin name>`` 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 <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
|
||||
|
|
@ -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::
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <strategy/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
|
||||
+++++++++++
|
||||
|
|
|
|||
|
|
@ -11,11 +11,24 @@ Vars plugins were partially implented in Ansible 2.0 and rewritten to be fully i
|
|||
The :doc:`host_group_vars <vars/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
|
||||
++++++++++++
|
||||
|
||||
|
|
|
|||
2
docs/templates/config.rst.j2
vendored
2
docs/templates/config.rst.j2
vendored
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
@{ title }@ @{ plugin_type }@
|
||||
@{ title }@ @{ plugin_type + 's' }@
|
||||
@{ '`' * title | length }@````````
|
||||
|
||||
{% if blurb %}
|
||||
|
|
|
|||
65
docs/templates/plugin.rst.j2
vendored
65
docs/templates/plugin.rst.j2
vendored
|
|
@ -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
|
|||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
{% if plugin_type != 'module' %}
|
||||
<th class="head">configuration</th>
|
||||
{% endif %}
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
{% for k in option_keys -%}
|
||||
|
|
@ -102,23 +107,48 @@ Options
|
|||
{% else %}
|
||||
<td>{% if v['choices'] -%}<ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice }@</li>{% endfor -%}</ul>{% endif -%}</td>
|
||||
{% endif %}
|
||||
{% if plugin_type != 'module' %}
|
||||
<td>
|
||||
{% if 'ini' in v %}
|
||||
<div> ini entries:
|
||||
{% for ini in v.get('ini') %}
|
||||
<p>[@{ ini.section }@ ]<br>@{ ini.key}@ = @{ v['default']|default('VALUE') }@</p>
|
||||
{% endfor %}
|
||||
</div>
|
||||
{% endif %}
|
||||
{% if 'env' in v %}
|
||||
{% for env in v.get('env') %}
|
||||
<div>env:@{ env.name }@</div>
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
{% if 'vars' in v %}
|
||||
{% for myvar in v.get('vars') %}
|
||||
<div>var: @{ myvar.name }@</div>
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</td>
|
||||
{% endif %}
|
||||
<td>
|
||||
{% if v.description is string %}
|
||||
<div>@{ v.description | replace('\n', '\n ') | html_ify }@</div>
|
||||
{% else %}
|
||||
{% for desc in v.description %}
|
||||
<div>@{ desc | replace('\n', '\n ') | html_ify }@</div>
|
||||
<p>@{ desc | replace('\n', '\n ') | html_ify }@</p>
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
{% if 'aliases' in v and v.aliases %}
|
||||
</br><div style="font-size: small;">aliases: @{ v.aliases|join(', ') }@</div>
|
||||
{% endif %}
|
||||
</td>
|
||||
</tr>
|
||||
{% else %}
|
||||
|
||||
<tr>
|
||||
<td rowspan="2">@{ k }@<br/><div style="font-size: small;">{% if v['version_added'] -%} (added in @{v['version_added']}@){% endif -%}</div></td>
|
||||
<td>{% if v.get('required', False) -%}yes{% else -%}no{% endif -%}</td>
|
||||
<td></td>
|
||||
{% if plugin_type != 'module' %}
|
||||
<td></td>
|
||||
{% endif %}
|
||||
<td></td>
|
||||
<td>
|
||||
{% 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 <common_return_values>`, the following are the fields unique to this module:
|
||||
Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this {{plugin_type}}:
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
|
@ -265,16 +295,12 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
|
|||
<td align=center>@{ returndocs[entry].contains[sub].sample }@</td>
|
||||
</tr>
|
||||
{% endfor %}
|
||||
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</td></tr>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
</table>
|
||||
</br>
|
||||
</br>
|
||||
</br></br>
|
||||
{% 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<https://access.redhat.com/articles/rhel-top-support-policies>`_
|
||||
For more information about Red Hat's this support of this @{ plugin_type }@,
|
||||
please refer to this `knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>_`
|
||||
|
||||
{% 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 %}.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,9 @@ __metaclass__ = type
|
|||
DOCUMENTATION = '''
|
||||
name: openstack
|
||||
plugin_type: inventory
|
||||
authors:
|
||||
- Marco Vito Moscaritolo <marco@agavee.com>
|
||||
- Jesse Keating <jesse.keating@rackspace.com>
|
||||
short_description: OpenStack inventory source
|
||||
description:
|
||||
- Get inventory hosts from OpenStack clouds
|
||||
|
|
|
|||
Loading…
Reference in a new issue