diff --git a/designate/backend/__init__.py b/designate/backend/__init__.py index 295a178fe..a95a76418 100644 --- a/designate/backend/__init__.py +++ b/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) diff --git a/designate/coordination.py b/designate/coordination.py index 21641d36f..01652194d 100644 --- a/designate/coordination.py +++ b/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 diff --git a/designate/pool_manager/service.py b/designate/pool_manager/service.py index d633365b3..cb62eb8f0 100644 --- a/designate/pool_manager/service.py +++ b/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)) diff --git a/designate/worker/service.py b/designate/worker/service.py index 60d10ab88..8385ceb2b 100644 --- a/designate/worker/service.py +++ b/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)) diff --git a/doc/source/contributor/backends/agent.rst b/doc/source/admin/backends/agent.rst similarity index 100% rename from doc/source/contributor/backends/agent.rst rename to doc/source/admin/backends/agent.rst diff --git a/doc/source/contributor/backends/bind9.rst b/doc/source/admin/backends/bind9.rst similarity index 98% rename from doc/source/contributor/backends/bind9.rst rename to doc/source/admin/backends/bind9.rst index dc0c2a842..0dfb39a8b 100644 --- a/doc/source/contributor/backends/bind9.rst +++ b/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 ============= diff --git a/doc/source/contributor/backends/djbdns_agent.rst b/doc/source/admin/backends/djbdns_agent.rst similarity index 100% rename from doc/source/contributor/backends/djbdns_agent.rst rename to doc/source/admin/backends/djbdns_agent.rst diff --git a/doc/source/contributor/backends/gdnsd_agent.rst b/doc/source/admin/backends/gdnsd_agent.rst similarity index 100% rename from doc/source/contributor/backends/gdnsd_agent.rst rename to doc/source/admin/backends/gdnsd_agent.rst diff --git a/doc/source/contributor/backends/index.rst b/doc/source/admin/backends/index.rst similarity index 86% rename from doc/source/contributor/backends/index.rst rename to doc/source/admin/backends/index.rst index a4bd4079b..a9431802a 100644 --- a/doc/source/contributor/backends/index.rst +++ b/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` diff --git a/doc/source/contributor/backends/infoblox.rst b/doc/source/admin/backends/infoblox.rst similarity index 100% rename from doc/source/contributor/backends/infoblox.rst rename to doc/source/admin/backends/infoblox.rst diff --git a/doc/source/contributor/backends/knot2_agent.rst b/doc/source/admin/backends/knot2_agent.rst similarity index 100% rename from doc/source/contributor/backends/knot2_agent.rst rename to doc/source/admin/backends/knot2_agent.rst diff --git a/doc/source/contributor/backends/msdns_agent.rst b/doc/source/admin/backends/msdns_agent.rst similarity index 100% rename from doc/source/contributor/backends/msdns_agent.rst rename to doc/source/admin/backends/msdns_agent.rst diff --git a/doc/source/contributor/backends/pdns4.rst b/doc/source/admin/backends/pdns4.rst similarity index 100% rename from doc/source/contributor/backends/pdns4.rst rename to doc/source/admin/backends/pdns4.rst diff --git a/doc/source/contributor/backends/powerdns.rst b/doc/source/admin/backends/powerdns.rst similarity index 100% rename from doc/source/contributor/backends/powerdns.rst rename to doc/source/admin/backends/powerdns.rst diff --git a/doc/source/contributor/backends/sample_yaml_snippets/agent.yaml b/doc/source/admin/backends/sample_yaml_snippets/agent.yaml similarity index 100% rename from doc/source/contributor/backends/sample_yaml_snippets/agent.yaml rename to doc/source/admin/backends/sample_yaml_snippets/agent.yaml diff --git a/doc/source/contributor/backends/sample_yaml_snippets/bind.yaml b/doc/source/admin/backends/sample_yaml_snippets/bind.yaml similarity index 100% rename from doc/source/contributor/backends/sample_yaml_snippets/bind.yaml rename to doc/source/admin/backends/sample_yaml_snippets/bind.yaml diff --git a/doc/source/contributor/backends/sample_yaml_snippets/pdns4.yaml b/doc/source/admin/backends/sample_yaml_snippets/pdns4.yaml similarity index 100% rename from doc/source/contributor/backends/sample_yaml_snippets/pdns4.yaml rename to doc/source/admin/backends/sample_yaml_snippets/pdns4.yaml diff --git a/doc/source/contributor/backends/sample_yaml_snippets/powerdns.yaml b/doc/source/admin/backends/sample_yaml_snippets/powerdns.yaml similarity index 100% rename from doc/source/contributor/backends/sample_yaml_snippets/powerdns.yaml rename to doc/source/admin/backends/sample_yaml_snippets/powerdns.yaml diff --git a/doc/source/admin/config.rst b/doc/source/admin/config.rst new file mode 100644 index 000000000..ba67cfcc7 --- /dev/null +++ b/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 diff --git a/doc/source/admin/ha.rst b/doc/source/admin/ha.rst new file mode 100644 index 000000000..90793aa4a --- /dev/null +++ b/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:/// + 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://: + +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 diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index e2f6dda1c..5351582e8 100644 --- a/doc/source/admin/index.rst +++ b/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 diff --git a/doc/source/admin/policy.rst b/doc/source/admin/policy.rst index bb0b74caa..43aafb67e 100644 --- a/doc/source/admin/policy.rst +++ b/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`. diff --git a/doc/source/admin/samples/config.rst b/doc/source/admin/samples/config.rst new file mode 100644 index 000000000..adfbb8fa9 --- /dev/null +++ b/doc/source/admin/samples/config.rst @@ -0,0 +1,6 @@ +============== +designate.conf +============== + +.. literalinclude:: ../../_static/designate.conf.sample + :language: ini diff --git a/doc/source/admin/samples/index.rst b/doc/source/admin/samples/index.rst index 56cf78b07..0dc317128 100644 --- a/doc/source/admin/samples/index.rst +++ b/doc/source/admin/samples/index.rst @@ -9,3 +9,4 @@ found below: .. toctree:: policy-yaml.rst + config.rst diff --git a/doc/source/admin/samples/policy-yaml.rst b/doc/source/admin/samples/policy-yaml.rst index c9c453369..e0d8da416 100644 --- a/doc/source/admin/samples/policy-yaml.rst +++ b/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 diff --git a/doc/source/contributor/support-matrix.ini b/doc/source/admin/support-matrix.ini similarity index 97% rename from doc/source/contributor/support-matrix.ini rename to doc/source/admin/support-matrix.ini index 5b0c32a24..ffbcd94fe 100644 --- a/doc/source/contributor/support-matrix.ini +++ b/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 [backends.backend-impl-akamai] -maintainers=HP DNSaaS Team [backends.backend-impl-agent] diff --git a/doc/source/contributor/support-matrix.rst b/doc/source/admin/support-matrix.rst similarity index 95% rename from doc/source/contributor/support-matrix.rst rename to doc/source/admin/support-matrix.rst index 76a9aa4bf..75160c4f8 100644 --- a/doc/source/contributor/support-matrix.rst +++ b/doc/source/admin/support-matrix.rst @@ -1,4 +1,6 @@ +.. _driver_matrix: + DNS Server Driver Support Matrix ================================ diff --git a/doc/source/conf.py b/doc/source/conf.py index bccea7179..f2cb2713b 100644 --- a/doc/source/conf.py +++ b/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'] diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 074618a6c..b4b5b56a2 100644 --- a/doc/source/configuration/index.rst +++ b/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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 287907b83..3802524a0 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -11,8 +11,6 @@ Contents: :maxdepth: 2 getting-involved - support-matrix - backends/index Designate Tempest Plugin architecture gmr diff --git a/test-requirements.txt b/test-requirements.txt index 956d9ddcc..d1c617056 100644 --- a/test-requirements.txt +++ b/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