centersl/ansible-docs
1
0
Fork 0
mirror of https://github.com/ansible/ansible-documentation.git synced 2026-03-26 13:18:58 +07:00
Code Issues Packages Projects Releases Wiki Activity

cache: disclaimer for using cache (#3168)

Browse Source 
* cache: disclaimer for using cache

Fixes: #3167

Signed-off-by: Abhijeet Kasurde <Akasurde@redhat.com>

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Signed-off-by: Abhijeet Kasurde <Akasurde@redhat.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Abhijeet Kasurde
2026-01-21 04:49:08 -08:00
committed by GitHub
parent 6476659151
commit f1967b117e
2 changed files with 18 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/docsite/rst/dev_guide/developing_plugins.rst
View File

@@ -256,6 +256,14 @@ If your cache plugin stores JSON, use ``AnsibleJSONEncoder`` in the ``_dump`` or
For example cache plugins, see the source code for the `cache plugins included with Ansible Core <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/cache>`_.
Note that cache plugin implementation is an internal detail, and should not be relied upon by external uses such as interrogation or consumption in a playbook.
It is assumed that a cache produced at any point in time, is usable at any future point in time, as the underlying implementation, or information provided within may change.
If the planned use case of a cache is external interrogation or consumption, we recommend to be explicit about the fetching and storing of that data, such as creating a playbook that gathers facts and stores them in the format
you need them in,
and then stores that data explicitly outside of the concept of a cache, where it can be relied upon.
.. _developing_callbacks:
Callback plugins

10
docs/docsite/rst/plugins/cache.rst
View File

@@ -13,6 +13,10 @@ The default cache plugin is the :ref:`memory <memory_cache>` plugin, which only
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. If necessary, you can :ref:`create custom cache plugins <developing_cache_plugins>`.
A cache plugin implementation is an internal implementation detail, and should not be relied upon by external uses. The format of the data or how it is stored is a concern for the plugin, and this data may change or even be absent. As such, the cache of :ansplugin:`ansible.builtin.jsonfile#cache`, :ansplugin:`community.general.redis#cache`, or any other cache plugin should not be interrogated external to the cache plugin itself.
The cache maintained by a cache plugin is only to be used indirectly within a playbook, without any concept that the data even came from a cache.
.. _enabling_cache:
Enabling fact cache plugins
@@ -42,6 +46,12 @@ To enable a custom cache plugin, save it in one of the directory sources configu
You also need to configure other settings specific to each plugin. Consult the individual plugin documentation or the Ansible :ref:`configuration <ansible_configuration_settings>` for more details.
.. note::
The existence of the cache, or an individual item in the cache should not be a hard requirement. Playbooks should not be written in a way as to potentially failing if the cache or a specific value is missing.
A cache hit or miss should not affect a playbook operation.
Enabling inventory cache plugins
--------------------------------