Docs Refactor

* Move backend docs to admin guide
* Add oslo.config sphinx extention
* Add HA guide
* Update drivers to log driver grade

Change-Id: I4a364a0d1a0656f26d3a4c3b7baad7e43cddcb16

designate/backend/__init__.py

@@ -19,11 +19,20 @@ from designate.backend import base
 
 LOG = logging.getLogger(__name__)
 
+GOOD_STATUSES = [
+    'integrated', 'grades.master-compatible', 'release-compatible'
+]
 
-def get_backend(type_, target):
-    # TODO(kiall): Type is attached to the target, use it.
-    LOG.debug("Loading backend driver: %s" % type_)
 
-    cls = base.Backend.get_driver(type_)
+def get_backend(target):
+    cls = base.Backend.get_driver(target.type)
+
+    msg = "Backend Driver '%s' loaded. Has status of '%s'" \
+          % (target.type, cls.__backend_status__)
+
+    if cls.__backend_status__ in GOOD_STATUSES:
+        LOG.info(msg)
+    else:
+        LOG.warning(msg)
 
     return cls(target)

designate/coordination.py

@@ -40,7 +40,8 @@ coordination_opts = [
     cfg.StrOpt('backend_url',
                help='The backend URL to use for distributed coordination. If '
                     'unset services that need coordination will function as '
-                    'a standalone service.'),
+                    'a standalone service. This is a `tooz` url - see '
+                    'https://docs.openstack.org/tooz/latest/user/compatibility.html'),  # noqa
     cfg.FloatOpt('heartbeat_interval',
                  default=1.0,
                  help='Number of seconds between heartbeats for distributed '
@@ -73,6 +74,7 @@ class CoordinationMixin(object):
 
         if CONF.coordination.backend_url is not None:
             backend_url = cfg.CONF.coordination.backend_url
+
             self._coordinator = tooz.coordination.get_coordinator(
                 backend_url, self._coordination_id)
             self._coordination_started = False

designate/pool_manager/service.py

@@ -122,8 +122,7 @@ class Service(service.RPCService, coordination.CoordinationMixin,
         for target in self.pool.targets:
             # Fetch an instance of the Backend class, passing in the options
             # and masters
-            self.target_backends[target.id] = backend.get_backend(
-                target.type, target)
+            self.target_backends[target.id] = backend.get_backend(target)
 
         LOG.info(_LI('%d targets setup'), len(self.pool.targets))
 

designate/worker/service.py

@@ -49,8 +49,7 @@ class Service(service.RPCService, service.Service):
     def _setup_target_backends(self, pool):
         for target in pool.targets:
             # Fetch an instance of the Backend class
-            target.backend = backend.get_backend(
-                    target.type, target)
+            target.backend = backend.get_backend(target)
 
         LOG.info(_LI('%d targets setup'), len(pool.targets))
 

doc/source/admin/backends/bind9.rst

@@ -13,6 +13,8 @@
     License for the specific language governing permissions and limitations
     under the License.
 
+.. _bind9_backend_docs:
+
 Bind9 Backend
 =============
 

doc/source/admin/backends/index.rst

@@ -19,7 +19,10 @@ DNS Server Plugin Documentation
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :glob:
 
    *
+
+For a list of drivers and the status of each drivers testing please go to
+:ref:`driver_matrix`

doc/source/admin/config.rst

@@ -0,0 +1,9 @@
+====================
+Config Documentation
+====================
+
+The following is an overview of all available configuration in Designate. For a
+sample configuration file, refer to :doc:`samples/config`.
+
+.. show-options::
+   :config-file: etc/designate/designate-config-generator.conf

doc/source/admin/ha.rst

@@ -0,0 +1,229 @@
+.. _ha:
+
+=======================
+High Availability Guide
+=======================
+
+Designate supports running all of its components services in "active-active"
+HA modes.
+
+Some services require some extra setup to ensure that they can work in
+active-active, and the services are listed below.
+
+designate-api
+=============
+
+Needs Access to:
+----------------
+
+* AMQP
+
+.. blockdiag::
+
+   blockdiag {
+
+      loadbalancer [label="L7 Load Balancer", stacked];
+      amqp_servers [label="AMQP Servers", stacked]
+      group api_servers {
+        label = "API Servers";
+        api_server_1 [label="API Server 1"];
+        api_server_2 [label="API Server 2"];
+        api_server_3 [label="API Server 3"];
+      }
+      loadbalancer -> api_server_1, api_server_2, api_server_3;
+      api_server_1, api_server_2, api_server_3 -> amqp_servers;
+   }
+
+Notes
+-----
+
+To run multiple `designate-api` services, you should run the services behind
+a load balancer.
+
+When behind the load balancer, you may need to set the following:
+
+.. code-block:: ini
+
+   [service:api]
+   api_base_uri = http://<load balancer URI>/
+   enable_host_header = True
+
+Or the following:
+
+.. code-block:: ini
+
+   [oslo_middleware]
+   enable_proxy_headers_parsing = true
+
+And then the load balancer to set appropriate headers (e.g. enable `mod_proxy`
+in apache.)
+
+designate-central
+=================
+
+Needs Access to:
+----------------
+
+* AMQP
+* Database
+
+.. blockdiag::
+
+   blockdiag {
+
+      amqp_servers [label="AMQP Servers", stacked]
+      db_servers [label="Database Servers", stacked, shape=flowchart.database]
+      group designate_central_servers {
+        label = "designate-central Servers";
+        designate_central_server_1 [label="designate-central Server 1", width=256];
+        designate_central_server_2 [label="designate-central Server 2", width=256];
+        designate_central_server_3 [label="designate-central Server 3", width=256];
+      }
+      amqp_servers <-> designate_central_server_1, designate_central_server_2, designate_central_server_3;
+      designate_central_server_1, designate_central_server_2, designate_central_server_3 -> db_servers;
+   }
+
+Notes
+-----
+
+You can run as many `designate-central` services as needed, as long as they all
+have access to the AMQP server(s), work will be distributed across all of them.
+
+designate-mdns
+==============
+
+Needs Access to:
+----------------
+
+* AMQP
+* Database
+* DNS Servers
+
+.. blockdiag::
+
+   blockdiag {
+
+      amqp_servers [label="AMQP Servers", stacked]
+      dns_servers [label="DNS Servers", stacked, shape="cloud"]
+      db_servers [label="Database Servers", stacked, shape=flowchart.database]
+      group designate_mdns_servers {
+        label = "designate-mdns Servers";
+        designate_mdns_server_1 [label="designate-mdns Server 1", width=256];
+        designate_mdns_server_2 [label="designate-mdns Server 2", width=256];
+        designate_mdns_server_3 [label="designate-mdns Server 3", width=256];
+      }
+      amqp_servers <-> designate_mdns_server_1, designate_mdns_server_2, designate_mdns_server_3;
+      designate_mdns_server_1, designate_mdns_server_2, designate_mdns_server_3 <- db_servers;
+      designate_mdns_server_1, designate_mdns_server_2, designate_mdns_server_3 -> dns_servers;
+   }
+
+Notes
+-----
+
+You can run as many `designate-mdns` services as needed, as long as they all
+have access to the AMQP server(s), work will be distributed across all of them.
+
+designate-worker
+================
+
+Needs Access to:
+----------------
+
+* AMQP
+* DNS Servers
+
+.. blockdiag::
+
+   blockdiag {
+
+      amqp_servers [label="AMQP Servers", stacked]
+      dns_servers [label="DNS Servers", stacked, shape="cloud"]
+      group designate_worker_servers {
+        label = "designate-worker Servers";
+        designate_worker_server_1 [label="designate-worker Server 1", width=256];
+        designate_worker_server_2 [label="designate-worker Server 2", width=256];
+        designate_worker_server_3 [label="designate-worker Server 3", width=256];
+      }
+      amqp_servers <-> designate_worker_server_1, designate_worker_server_2, designate_worker_server_3;
+      designate_worker_server_1, designate_worker_server_2, designate_worker_server_3 -> dns_servers;
+   }
+
+Notes
+-----
+
+You can run as many `designate-worker` services as needed, as long as they all
+have access to the AMQP server(s), work will be distributed across all of them.
+
+designate-producer
+==================
+
+Needs Access to:
+----------------
+
+* AMQP
+* DLM
+
+.. blockdiag::
+
+   blockdiag {
+
+      amqp_servers [label="AMQP Servers", stacked]
+      dlm_servers [label="DLM Servers", stacked]
+      group designate_producer_servers {
+        label = "designate-producer Servers";
+        designate_producer_server_1 [label="designate-producer Server 1", width=256];
+        designate_producer_server_2 [label="designate-producer Server 2", width=256];
+        designate_producer_server_3 [label="designate-producer Server 3", width=256];
+      }
+      amqp_servers <-> designate_producer_server_1, designate_producer_server_2, designate_producer_server_3;
+      designate_producer_server_1, designate_producer_server_2, designate_producer_server_3 -> dlm_servers;
+   }
+
+Notes
+-----
+
+You can run as many `designate-producer` services as needed, as long as they
+all have access to the AMQP server(s), and a distributed lock manager,
+work will be sharded across all the services.
+
+You will need to set a coordination `backend_url`. This needs to be a DLM
+that is supported by tooz, that supports group membership.
+See `tooz driver list`_ for available drivers
+
+.. warning:: Failure to set a `backend_url` can cause unexpected consequences, and may result in some periodic tasks being ran more than once.
+
+.. code-block:: ini
+
+   [coordination]
+   backend_url = kazoo://<zookeeper url>:<zookeeper port>
+
+designate-sink
+==============
+
+Needs Access to:
+----------------
+
+* AMQP
+
+.. blockdiag::
+
+   blockdiag {
+
+      amqp_servers [label="AMQP Servers", stacked]
+      group designate_sink_servers {
+        label = "designate-sink Servers";
+        designate_sink_server_1 [label="designate-sink Server 1", width=256];
+        designate_sink_server_2 [label="designate-sink Server 2", width=256];
+        designate_sink_server_3 [label="designate-sink Server 3", width=256];
+      }
+      amqp_servers <-> designate_sink_server_1, designate_sink_server_2, designate_sink_server_3;
+   }
+
+Notes
+-----
+
+You can run as many `designate-sink` services as needed, as long as they all
+have access to the AMQP server(s), work will be distributed across all of them.
+
+
+.. _tooz driver list: https://docs.openstack.org/tooz/latest/user/compatibility.html#grouping

doc/source/admin/index.rst

@@ -8,9 +8,11 @@ and operating Designate.
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    tlds
+   backends/index
+   ha
    pools
    pool-scheduler
    multiple-pools
@@ -18,9 +20,11 @@ Contents:
    quotas
    designate-manage
    policy
+   config
    notifications
    production-guidelines
    upgrades/index
    troubleshooting
    samples/index
+   support-matrix
 

doc/source/admin/policy.rst

@@ -1,6 +1,6 @@
-=============
-Sample Policy
-=============
+====================
+Policy Documentation
+====================
 
 The following is an overview of all available policies in Designate. For a
 sample configuration file, refer to :doc:`samples/policy-yaml`.

doc/source/admin/samples/config.rst

@@ -0,0 +1,6 @@
+==============
+designate.conf
+==============
+
+.. literalinclude:: ../../_static/designate.conf.sample
+    :language: ini

doc/source/admin/samples/index.rst

@@ -9,3 +9,4 @@ found below:
 .. toctree::
 
    policy-yaml.rst
+   config.rst

doc/source/admin/samples/policy-yaml.rst

@@ -6,3 +6,4 @@ Use the ``policy.yaml`` file to define additional access controls that apply to
 the DNS service:
 
 .. literalinclude:: ../../_static/designate.policy.yaml.sample
+    :language: yaml

doc/source/admin/support-matrix.ini

@@ -40,7 +40,8 @@ maintainers=Designate Team
 notes=None
 type=xfr
 in-tree=True
-
+docs=None
+config=None
 
 [backends]
 backend-impl-bind9=Bind9
@@ -61,6 +62,8 @@ backend-impl-msdns-agent=Microsoft DNS (Agent)
 
 
 [backends.backend-impl-bind9]
+docs=bind9_backend_docs
+config=backends/sample_yaml_snippets/bind.yaml
 
 [backends.backend-impl-pdns4]
 
@@ -73,10 +76,8 @@ notes=This has been replaced by the pdns4 backend for future releases
 status=untested
 
 [backends.backend-impl-dynect]
-maintainers=HP DNSaaS Team <dnsaas@hp.com>
 
 [backends.backend-impl-akamai]
-maintainers=HP DNSaaS Team <dnsaas@hp.com>
 
 [backends.backend-impl-agent]
 

doc/source/admin/support-matrix.rst

@@ -1,4 +1,6 @@
 
+.. _driver_matrix:
+
 DNS Server Driver Support Matrix
 ================================
 

doc/source/conf.py

@@ -30,10 +30,12 @@ sys.path.insert(0, os.path.abspath('./'))
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
               'sphinxcontrib.httpdomain',
+              'sphinxcontrib.blockdiag',
               'ext.support_matrix',
               'ext.custom_css',
               'openstackdocstheme',
               'oslo_config.sphinxconfiggen',
+              'oslo_config.sphinxext',
               'oslo_policy.sphinxpolicygen',
               'oslo_policy.sphinxext']
 
@@ -49,6 +51,8 @@ sample_config_basename = '_static/designate'
 policy_generator_config_file = '../../etc/designate/designate-policy-generator.conf'
 sample_policy_basename = '_static/designate'
 
+blockdiag_antialias = True
+blockdiag_html_image_format = "SVG"
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/source/configuration/index.rst

@@ -42,6 +42,3 @@ directory.
 #. You can generate full sample *designate.conf* (if it does not already exist)::
 
     $ oslo-config-generator --config-file etc/designate/designate-config-generator.conf --output-file /etc/designate/designate.conf
-
-.. literalinclude:: ../_static/designate.conf.sample
-    :language: ini

doc/source/contributor/index.rst

@@ -11,8 +11,6 @@ Contents:
    :maxdepth: 2
 
    getting-involved
-   support-matrix
-   backends/index
    Designate Tempest Plugin <https://docs.openstack.org/designate-tempest-plugin/latest>
    architecture
    gmr

test-requirements.txt

@@ -12,6 +12,7 @@ requests-mock>=1.1.0 # Apache-2.0
 sphinx>=1.6.2 # BSD
 sphinxcontrib-httpdomain>=1.3.0 # BSD
 testtools>=2.2.0 # MIT
+sphinxcontrib-blockdiag>=1.5.4  # BSD
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 WebTest>=2.0.27 # MIT