From 8af81fe792afa2b80c9bb72d47975d7891f5c68c Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Mon, 20 Oct 2025 09:18:58 -0700 Subject: [PATCH] cache: disclaimer for using cache Fixes: #3167 Signed-off-by: Abhijeet Kasurde --- docs/docsite/rst/dev_guide/developing_plugins.rst | 7 +++++++ docs/docsite/rst/plugins/cache.rst | 10 ++++++++++ 2 files changed, 17 insertions(+) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 3be04aaa615..1f838674709 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -256,6 +256,13 @@ 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 `_. +It is recommended 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, it would be a better recommendation to be explicit about the fetching and storing of that data, such as creating a playbook that gathers facts, +and then stores that data explicitly outside of the concept of a cache, where it can be relied upon. + .. _developing_callbacks: Callback plugins diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index 5e877a7670e..20b284c3b19 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -13,6 +13,10 @@ The default cache plugin is the :ref:`memory ` 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 `. +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 jsonfile, redis, 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 ` 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 --------------------------------