Toshio Kuratomi 9dda393d70

* Build documentation for Ansible-2.10 (formerly known as ACD).

Builds plugin docs from collections whose source is on galaxy

The new command downloads collections from galaxy, then finds the
plugins inside of them to get the documentation for those plugins.

* Update the python syntax checks
  * docs builds can now require python 3.6+.

* Move plugin formatter code out to an external tool, antsibull-docs.
  Collection owners want to be able to extract docs for their own
  websites as well.
* The jinja2 filters, tests, and other support code have moved to antsibull
* Remove document_plugins as that has now been integrated into antsibull-docs

* Cleanup and bugfix to other build script code:
  * The Commands class needed to have its metaclass set for abstractmethod
    to work correctly
  * Fix lint issues in some command plugins

* Add the docs/docsite/rst/collections to .gitignore as
  everything in that directory will be generated so we don't want any of
  it saved in the git repository
* gitignore the build dir and remove edit docs link on module pages

* Add docs/rst/collections as a directory to remove on make clean
* Split the collections docs from the main docs

* remove version and edit on github
* remove version banner for just collections
* clarify examples need collection keyword defined

* Remove references to plugin documentation locations that no longer exist.
  * Perhaps the pages in plugins/*.rst should be deprecated
    altogether and their content moved?
  * If not, perhaps we want to rephrase and link into the collection
    documentation?
  * Or perhaps we want to link to the plugins which are present in
    collections/ansible/builtin?

* Remove PYTHONPATH from the build-ansible calls
  One of the design goals of the build-ansible.py script was for it to
  automatically set its library path to include the checkout of ansible
  and the library of code to implement itself.  Because it automatically
  includes the checkout of ansible, we don't need to set PYTHONPATH in
  the Makefile any longer.

* Create a command to only build ansible-base plugin docs
  * When building docs for devel, only build the ansible-base docs for
    now.  This is because antsibull needs support for building a "devel
    tree" of docs.  This can be changed once that is implemented
  * When building docs for the sanity tests, only build the ansible-base
    plugin docs for now.  Those are the docs which are in this repo so
    that seems appropriate for now.

2020-07-17 13:07:35 -07:00

4.6 KiB

Raw Blame History

Cache Plugins

Cache plugins allow Ansible to store gathered facts or inventory source data without the performance hit of retrieving them from source.

The default cache plugin is the memory <memory_cache> 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. Some of these cache plugins write to files, others write to databases.

You can use different cache plugins for inventory and facts. If you enable inventory caching without setting an inventory-specific cache plugin, Ansible uses the fact cache plugin for both facts and inventory.

Enabling Fact Cache Plugins

Fact caching is always enabled. However, only one fact cache plugin can be active at a time. You can select the cache plugin to use for fact caching in the Ansible configuration, either with an environment variable:

export ANSIBLE_CACHE_PLUGIN=jsonfile

or in the ansible.cfg file:

[defaults]
fact_caching=redis

If the cache plugin is in a collection use the fully qualified name:

[defaults]
fact_caching = namespace.collection_name.cache_plugin_name

To enable a custom cache plugin, save it in a cache_plugins directory adjacent to your play, inside a role, or in one of the directory sources configured in ansible.cfg <ansible_configuration_settings>.

You also need to configure other settings specific to each plugin. Consult the individual plugin documentation or the Ansible configuration <ansible_configuration_settings> for more details.

Enabling Inventory Cache Plugins

Inventory caching is disabled by default. To cache inventory data, you must enable inventory caching and then select the specific cache plugin you want to use. Not all inventory plugins support caching, so check the documentation for the inventory plugin(s) you want to use. You can enable inventory caching with an environment variable:

export ANSIBLE_INVENTORY_CACHE=True

or in the ansible.cfg file:

[inventory]
cache=True

or if the inventory plugin accepts a YAML configuration source, in the configuration file:

# dev.aws_ec2.yaml
plugin: aws_ec2
cache: True

Only one inventory cache plugin can be active at a time. You can set it with an environment variable:

export ANSIBLE_INVENTORY_CACHE_PLUGIN=jsonfile

or in the ansible.cfg file:

[inventory]
cache_plugin=jsonfile

or if the inventory plugin accepts a YAML configuration source, in the configuration file:

# dev.aws_ec2.yaml
plugin: aws_ec2
cache_plugin: jsonfile

To cache inventory with a custom plugin in your plugin path, follow the developer guide on cache plugins<developing_cache_plugins>.

To cache inventory with a cache plugin in a collection, use the FQCN:

[inventory]
cache_plugin=collection_namespace.collection_name.cache_plugin

If you enable caching for inventory plugins without selecting an inventory-specific cache plugin, Ansible falls back to caching inventory with the fact cache plugin you configured. Consult the individual inventory plugin documentation or the Ansible configuration <ansible_configuration_settings> for more details.

Using Cache Plugins

Cache plugins are used automatically once they are enabled.

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 documentation and examples.

action_plugins: Ansible Action plugins
callback_plugins: Ansible callback plugins
connection_plugins: Ansible connection plugins
inventory_plugins: Ansible inventory plugins
shell_plugins: Ansible Shell plugins
strategy_plugins: Ansible Strategy plugins
vars_plugins: Ansible Vars plugins
User Mailing List: Have a question? Stop by the google group!
webchat.freenode.net: #ansible IRC chat channel

4.6 KiB Raw Blame History