cache: disclaimer for using cache (#3168)

* cache: disclaimer for using cache

Fixes: #3167

Signed-off-by: Abhijeet Kasurde <[email protected]>

* Apply suggestions from code review

Co-authored-by: Felix Fontein <[email protected]>

* Apply suggestions from code review

Co-authored-by: Felix Fontein <[email protected]>

---------

Signed-off-by: Abhijeet Kasurde <[email protected]>
Co-authored-by: Felix Fontein <[email protected]>

Author: Akasurde

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -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

docs/docsite/rst/plugins/cache.rst

@@ -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
 --------------------------------