Skip to content

Improve documentation about cache plugins #3167

@sivel

Description

@sivel

NOTE: This issue is mainly for the core team to action, but if the information provided here is actionable for anyone else with a good understanding about the goals of a "cache" in general, feel free to contribute.

There have been a number of issues, raised that can largely be described as a potential misunderstanding of caching in general. I'll attempt to enumerate some of what I believe to be problems:

  1. 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.
  2. 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 shouldn't affect a playbook operation.
  3. This is almost part of the previous, but it should not be 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.
  4. 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. However, going back to the previous, note that the data provided by fact gathering can change, especially between versions of ansible-core.

At the moment, cache plugins are really only covered within docs/docsite/rst/plugins/cache.rst, I am not sure if this new information should be documented there, or covered elsewhere.

Metadata

Metadata

Assignees

Labels

needs_triageNeeds a first human triage before being processed.

Type

No type

Projects

Status

🆕 Triage

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions