replace our memcached-based fact cache implementation with local files

see: https://github.com/ansible/ansible-tower/issues/7840

1 files changed, 32 insertions, 13 deletions

diff --git a/docs/fact_cache.md b/docs/fact_cache.md
index d1716d8aec..72ad41b759 100644
--- a/docs/fact_cache.md
+++ b/docs/fact_cache.md
@@ -1,21 +1,40 @@
-# Tower as an Ansible Fact Cache
-Tower can store and retrieve per-host facts via an Ansible Fact Cache Plugin. This behavior is configurable on a per-job-template basis. When enabled, Tower will serve fact requests for all Hosts in an Inventory related to the Job running. This allows users to use Job Templates with `--limit` while still having access to the entire Inventory of Host facts. The Tower Ansible Fact Cache supports a global timeout settings that it enforces per-host. The setting is available in the CTiT interface under the Jobs category with the name `ANSIBLE_FACT_CACHE_TIMEOUT` and is in seconds.
+# AWX as an Ansible Fact Cache
+AWX can store and retrieve per-host facts via an Ansible Fact Cache Plugin.
+This behavior is configurable on a per-job-template basis. When enabled, AWX
+will serve fact requests for all Hosts in an Inventory related to the Job
+running. This allows users to use Job Templates with `--limit` while still
+having access to the entire Inventory of Host facts.
 
-## Tower Fact Cache Implementation Details
-### Tower Injection
-In order to understand the behavior of Tower as a fact cache you will need to understand how fact caching is achieved in Tower. Upon a Job invocation with `use_fact_cache=True`, Tower will inject, into memcached, all `ansible_facts` associated with each Host in the Inventory associated with the Job. Jobs invoked with `use_fact_cache=False` will not inject `ansible_facts` into memcached. The cache key is of the form `inventory_id-host_name` so that hosts with the same name in different inventories do not clash. A list of all hosts in the inventory is also injected into memcached with key `inventory_id` and value `[host_name1, host_name2, ..., host_name3]`.
+## AWX Fact Cache Implementation Details
+### AWX Injection
+In order to understand the behavior of AWX as a fact cache you will need to
+understand how fact caching is achieved in AWX. When a Job launches with
+`use_fact_cache=True`, AWX will write all `ansible_facts` associated with
+each Host in the associated Inventory as JSON files on the local file system
+(one JSON file per host).  Jobs invoked with `use_fact_cache=False` will not
+write `ansible_facts` files.
 
 ### Ansible plugin usage
-The Ansible fact cache plugin that ships with Tower will only be enabled on Jobs that have fact cache enabled, `use_fact_cache=True`. The fact cache plugin running in Ansible will connect to the same memcached instance. A `get()` call to the fact cache interface in Ansible will result in a looked into memcached for the host-specific set of facts. A `set()` call to the fact cache will result in an update to memcached record along with the modified time.
+When `use_fact_cache=True`, Ansible will be configured to use the `jsonfile`
+cache plugin.  Any `get()` call to the fact cache interface in Ansible will
+result in a JSON file lookup for the host-specific set of facts. Any `set()`
+call to the fact cache will result in a JSON file being written to the local
+file system.
 
-### Tower Cache to DB
-When a Job finishes running that has `use_fact_cache=True` enabled, Tower will go through memcached and get all records for the hosts in the Inventory. Any records with update times newer than the database per-host `ansible_facts_modified` value will result in the `ansible_facts`, `ansible_facts_modified` from memcached being saved to the database. Note that the last value of the Ansible fact cache is retained in `ansible_facts`. The globla timeout and/or individual job template `use_fact_cache` setting will not clear the per-host `ansible_facts`.
+### AWX Cache to DB
+When a Job with `use_fact_cache=True` finishes running, AWX will look at all
+of the local JSON files that represent the fact data.  Any records with file
+modification times that have increased (because Ansible updated the file via
+`cache.set()`) will result in the latest value being saved to the database.  On
+subsequent playbook runs, AWX will _only_ inject cached facts that are _newer_
+than `settings.ANSIBLE_FACT_CACHE_TIMEOUT` seconds.
 
-### Caching Behavior
-Tower will always inject the host `ansible_facts` into memcached. The Ansible Tower Fact Cache Plugin will choose to present the cached values to the user or not based on the per-host `ansible_facts_modified` time and the global `ANSIBLE_FACT_CACHE_TIMEOUT`.
-
-## Tower Fact Logging
-New and changed facts will be logged via Tower's logging facility. Specifically, to the `system_tracking` namespace or logger. The logging payload will include the fields: `host_name`, `inventory_id`, and `ansible_facts`. Where `ansible_facts` is a dictionary of all ansible facts for `host_name` in Tower Inventory `inventory_id`. 
+## AWX Fact Logging
+New and changed facts will be logged via AWX's logging facility. Specifically,
+to the `system_tracking` namespace or logger. The logging payload will include
+the fields: `host_name`, `inventory_id`, and `ansible_facts`. Where
+`ansible_facts` is a dictionary of all ansible facts for `host_name` in AWX
+Inventory `inventory_id`.
 
 ## Integration Testing
 * ensure `clear_facts` set's `hosts/<id>/ansible_facts` to `{}`