Add Memcached documentation

Change-Id: I25179d775647c2154302a7cc6c7c85878545429c
Closes-Bug: 1549960

designate/pool_manager/cache/impl_memcache/__init__.py

@@ -13,6 +13,14 @@
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations
 # under the License.
+
+"""
+    impl_memcache.__init__
+    ~~~~~~~~~~~~~~~~~~~~~~
+    Memcache interface
+    Docs: doc/source/memory-caching.rst
+"""""""""
+
 import six
 from oslo_config import cfg
 

doc/source/architecture.rst

@@ -79,3 +79,10 @@ Designate uses oslo.rpc for messaging between components, therefore it inherits
 Database/Storage
 -----------------------
 Storage drivers are drivers for a particular SQL/NoSQL server. Designate needs a SQLAlchemy-supported storage engine for the persistent storage of data. The recommended driver is MySQL.
+
+.. _memory-caching-summary:
+
+Memory caching
+-----------------------
+Designate also uses an in-memory caching system, currently implemented with Memcached, as an optional cache for Pool Manager.
+See :ref:`memory-caching-details`

doc/source/index.rst

@@ -66,6 +66,7 @@ Reference Documentation
    gmr
    support-matrix
    pools
+   memory-caching
 
 Source Documentation
 ====================

doc/source/memory-caching.rst

@@ -0,0 +1,64 @@
+
+.. _memory-caching-details:
+
+==============
+Memory caching
+==============
+
+This page documents how memory caching is used in Designate.
+
+Pool Manager can leverage a memory caching service to speed up its operations and significantly reduce traffic to the DNS resolvers.
+
+Upon zone creation, update and deletion, Pool Manager polls the resolvers through MiniDNS to check if the zone is present or absent and get the zone serial.
+When using Memcache, this information is cached for 1 hour (see expiration time).
+
+The cache is not involved in sending NOTIFY/AXFR/IXFR traffic.
+
+The available cache drivers are Memcached, Sqlalchemy or Noop. Set `cache_driver` to 'memcache', 'sqlalchemy' or 'noop' accordingly.
+
+Configuration
+=============
+
+The following block in /etc/designate/designate.conf is used to configure the caching system used by Pool Manager:
+
+.. code-block:: ini
+
+    #-----------------------
+    # Pool Manager Service
+    #-----------------------
+    [service:pool_manager]
+    <omitted lines>
+    # The cache driver to use
+    #cache_driver = memcache
+
+    #-----------------------
+    # Memcache Pool Manager Cache
+    #-----------------------
+    [pool_manager_cache:memcache]
+    #memcached_servers = None
+    #expiration = 3600
+
+.. note:: By configuring cache_driver = memcache (default configuration) and setting memcached_servers to None, Designate will use a simple, local cache.
+
+   Setting cache_driver to 'noop' will disable caching completely. This is not recommended.
+
+It is recommended to run a Memcached instance for any deployment scenarios running large zones receiving frequent updates.
+
+Deployment, monitoring and troubleshooting
+==========================================
+
+The contents of Memcached can be flushed at runtime without impacting Designate. The only effect is a temporary loss of performance while the cache is being rebuilt.
+
+Useful metrics that can be monitored are: to-and-from Memcached traffic, concurrent connections, size of the cache, cache hit ratio, key age (expiration time)
+
+To get a simple status snapshot:
+
+.. code-block:: console
+
+    echo stats | nc <memcached_ip_address> <memcached_port>
+
+When Pool Manager logging verbosity is set to DEBUG, the following log messages will be generated::
+
+    Cache hit! Retrieved status ... and serial ... for zone ... on nameserver ... with action ... from the cache.
+    Cache miss! Did not retrieve status and serial for zone ... on nameserver ... with action ... from the cache. Getting it from the server.
+

doc/source/production-architecture.rst

@@ -30,6 +30,7 @@ A Designate deploy breaks down into several key roles:
 - `Designate Pool Manager`_
 - `Message Queue`_
 - `Database`_ (MySQL or derivative)
+- `Memory caching`_
 - `DNS Backend`_
 
 Designate API
@@ -64,6 +65,10 @@ Designate needs a SQLAlchemy supported :ref:`database` engine for the persistent
 
 In a Multi-AZ environment, a MySQL Galera Cluster, built using Percona's MySQL packages has performed well.
 
+Memory Caching
+~~~~~~~~~~~~~~
+Designate optionally uses :ref:`memory-caching-summary` usually through a Memcached instance to speed up Pool Manager operations.
+
 DNS Backend
 ~~~~~~~~~~~
 Designate supports multiple backend implementations, PowerDNS, BIND and MySQL BIND, you are also free to implement your own backend to fit your needs, as well as extensions to provide extra functionality to complement existing backends.