Merge pull request #40312 from rallytime/cache-docs

Update minion data cache documentation

doc/ref/configuration/master.rst

@@ -471,7 +471,7 @@ are expected to reply from executions.
 .. conf_master:: cache
 
 ``cache``
----------------------
+---------
 
 Default: ``localfs``
 

doc/topics/cache/index.rst

@@ -4,18 +4,43 @@
 Minion Data Cache
 =================
 
+.. versionadded:: 2016.11.0
+
 The Minion data cache contains the Salt Mine data, minion grains and minion
-pillar info cached on the Salt master. By default Salt uses the `localfs` cache
-module to save the data in a msgpack file on the Salt master.  Other external
-data stores can also be used to store this data such as the `Consul` module.
+pillar information cached on the Salt Master. By default, Salt uses the ``localfs`` cache
+module to save the data in a ``msgpack`` file on the Salt Master.
+
+.. _pluggable-data-cache:
+
+Pluggable Data Cache
+====================
+
+While the default Minion data cache is the ``localfs`` cache, other external
+data stores can also be used to store this data such as the ``consul`` module.
+To configure a Salt Master to use a different data store, the :conf_master:`cache`
+setting needs to be established:
+
+.. code-block:: yaml
+
+    cache: consul
+
+The pluggable data cache streamlines using various Salt topologies such as a
+:ref:`Multi-Master <tutorial-multi-master>` or :ref:`Salt Syndics <syndic>` configuration
+by allowing the data stored on the Salt Master about a Salt Minion to be available to
+other Salt Syndics or Salt Masters that a Salt Minion is connected to.
+
+Additional minion data cache modules can be easily created by modeling the custom data
+store after one of the existing cache modules.
 
 See :ref:`cache modules <all-salt.cache>` for a current list.
 
 
+.. _configure-minion-data-cache:
+
 Configuring the Minion Data Cache
 =================================
 
-The default `localfs` Minion data cache module doesn't require any
+The default ``localfs`` Minion data cache module doesn't require any
 configuration.  External data cache modules with external data stores such as
 Consul require a configuration setting in the master config.
 

doc/topics/topology/syndic.rst

@@ -218,3 +218,16 @@ Syndic node.
     - :conf_master:`syndic_log_file`: path to the logfile (absolute or not)
     - :conf_master:`syndic_pidfile`: path to the pidfile (absolute or not)
     - :conf_master:`syndic_wait`: time in seconds to wait on returns from this syndic
+
+Minion Data Cache
+=================
+
+Beginning with Salt 2016.11.0, the :ref:`Pluggable Minion Data Cache <pluggable-data-cache>`
+was introduced. The minion data cache contains the Salt Mine data, minion grains, and minion
+pillar information cached on the Salt Master. By default, Salt uses the ``localfs`` cache
+module, but other external data stores can be used instead.
+
+Using a pluggable minion cache modules allows for the data stored on a Salt Master about
+Salt Minions to be replicated on other Salt Masters the Minion is connected to. Please see
+the :ref:`Minion Data Cache <cache>` documentation for more information and configuration
+examples.

doc/topics/tutorials/multimaster.rst

@@ -20,6 +20,16 @@ on both masters, and shared files need to be shared manually or use tools like
 the git fileserver backend to ensure that the :conf_master:`file_roots` are
 kept consistent.
 
+Beginning with Salt 2016.11.0, the :ref:`Pluggable Minion Data Cache <pluggable-data-cache>`
+was introduced. The minion data cache contains the Salt Mine data, minion grains, and minion
+pillar information cached on the Salt Master. By default, Salt uses the ``localfs`` cache
+module, but other external data stores can be used instead.
+
+Using a pluggable minion cache modules allows for the data stored on a Salt Master about
+Salt Minions to be replicated on other Salt Masters the Minion is connected to. Please see
+the :ref:`Minion Data Cache <cache>` documentation for more information and configuration
+examples.
+
 Summary of Steps
 ----------------
 

salt/cache/consul.py

@@ -2,17 +2,23 @@
 '''
 Minion data cache plugin for Consul key/value data store.
 
+.. versionadded:: 2016.11.2
+
 It is up to the system administrator to set up and configure the Consul
 infrastructure. All is needed for this plugin is a working Consul agent
-with a read-write access to the key-value storae.
+with a read-write access to the key-value store.
 
-The related documentation can be found here: https://www.consul.io/docs/index.html
+The related documentation can be found in the `Consul documentation`_.
 
-To enable this cache plugin the master will need the python client for
-Consul installed that could be easily done with `pip install python-consul`.
+To enable this cache plugin, the master will need the python client for
+Consul installed. This can be easily installed with pip:
 
-Optionally depending on the Consul agent configuration the following values
-could be set in the master config, these are the defaults:
+.. code-block: bash
+
+    pip install python-consul
+
+Optionally, depending on the Consul agent configuration, the following values
+could be set in the master config. These are the defaults:
 
 .. code-block:: yaml
 
@@ -24,17 +30,19 @@ could be set in the master config, these are the defaults:
     consul.dc: dc1
     consul.verify: True
 
-Related docs could be found here:
-* python-consul: https://python-consul.readthedocs.io/en/latest/#consul
+Related docs could be found in the `python-consul documentation`_.
 
-To use the consul as a minion data cache backend set the master `cache` config
-value to `consul`:
+To use the consul as a minion data cache backend, set the master ``cache`` config
+value to ``consul``:
 
 .. code-block:: yaml
 
     cache: consul
 
-.. versionadded:: 2016.11.2
+
+.. _`Consul documentation`: https://www.consul.io/docs/index.html
+.. _`python-consul documentation`: https://python-consul.readthedocs.io/en/latest/#consul
+
 '''
 from __future__ import absolute_import
 import logging

salt/cache/localfs.py

@@ -4,10 +4,10 @@ Cache data in filesystem.
 
 .. versionadded:: 2016.11.0
 
-The `localfs` Minion cache module is the default cache module and does not
+The ``localfs`` Minion cache module is the default cache module and does not
 require any configuration.
 
-Expirations can be set in the relevant config file (``/etc/salt/master`` for
+Expiration values can be set in the relevant config file (``/etc/salt/master`` for
 the master, ``/etc/salt/cloud`` for Salt Cloud, etc).
 '''
 from __future__ import absolute_import