openstack/designate
Code Issues Proposed changes

New Docs toctree

Browse Source 
With the goal of making these docs more useful, asettle helped
us out creating a new tree at the PTG:
https://etherpad.openstack.org/p/designate-ptg-docs

This is the implementation of that new tree. With some minor changes
to content. There's still a lot of work to do there.

Change-Id: Idb29c04cde298a32da430243ae62894e1a790176
This commit is contained in:
Tim Simmons 2017-03-02 21:12:31 +00:00
parent 25758b58e4
commit 50c3a46964
9 changed files with 95 additions and 193 deletions

4
doc/source/backends.rst

@ -13,8 +13,8 @@
License for the specific language governing permissions and limitations
under the License.
Backend Documentation
=====================
DNS Server Plugin Documentation
===============================
Contents:

93
doc/source/glossary.rst

@ -1,93 +0,0 @@
..
Copyright 2012 Endre Karlson for Bouvet ASA
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
============
Glossary
============
.. glossary::
agent
The Agent would be a standalone service that acts as a sort of mirror to
mdns. It would receive AXFR/IXFR, NOTIFYs, and other notifications and
perform changes to a DNS server through a plugin-style backend. The agent
is intended for deployments that may not be able to use mdns as a true DNS
Master.
api
HTTP REST API service for Designate
central
Software service running on a central management node that stores
information persistently in a backend storage using a configurable driver
like SQLAlchemy or other.
mdns
Also known as mini dns. This is a dns server with limited capabilities like
NOTIFY's, AXFR's and record queries. The pool manager uses mdns to transfer
data to/from the pool servers.
mq
A message queue, typically something like RabbitMQ or ZeroMQ
name server
A FQDN (or IP, but usually a FQDN) that is used to populate the NS Records
of a Designate Managed Zone. Each Pool will have a set of Name Servers,
which users then delegate to from their registrar.
node
A server, physical or virtual, running some aspect of the designate system.
pool
A collection of pool servers sharing similar attributes. Different pools
could have different capabilities - such as GeoIP / Round Robin DNS / Anycast.
pool manager
This is a service that is responsible for notifying pool servers of the
changes that have occurred. It also updates central once the changes are
live on the pool servers.
pool manager backend
A backend is used by the pool manager to transfer the data from storage to
name servers. There are backends that support PowerDNS, BIND, & NSD.
pool server
The DNS servers that are updated by the pool manager. These need not be the
same as the name servers. When they are different a mechanism outside of designate
is needed to ensure the data on pool servers is consistent with that on the
name servers.
private pool
A pool of ‘private’ DNS servers. These servers would typically allow non
standard TLDs (.dev , .local etc), and may not have the same level of
blacklist restrictions. They would be aimed at people with Neutron Networking,
and VPC style set ups, where access to the DNS server would come from trusted
networks (E.G. in-cloud - owned instances, and onsite resources connect by VPN)
This would allow customers to set DNS entries for internal servers, on domains
that would not be available on the public pools, and have them accessible
by internal users
secondary zone
A zone within Designate that has external Masters.
sink
Optional Software Service that is configured to listen to events from the Nova
or Neutron event queue and use the central service to generate simple A records
for instances as they are created, and delete A records as they are deleted.
storage
A backend for storing data/information persistently. Typically MongoDB or
a SQL based server software.

145
doc/source/index.rst

@ -2,75 +2,24 @@
Designate, a DNSaaS component for OpenStack
===========================================
Designate provides DNSaaS services for OpenStack:
* REST API for domain & record management
* Multi-tenant support
* Integrated with Keystone for authentication
* Framework in place to integrate with Nova and Neutron notifications (for auto-generated records)
* Support for PowerDNS and Bind9 out of the box
This document describes Designate for users, operation teams and contributors of the project.
This documentation is generated by the Sphinx toolkit and lives in the `source tree`_. Additional documentation on Designate may
also be found on the `OpenStack wiki`_.
General documentation
=====================
New to Designate? Start here:
.. toctree::
:maxdepth: 1
architecture
glossary
getting-involved
User documentation
==================
.. toctree::
:maxdepth: 1
:glob:
howtos/*
rest
Operations documentation
========================
Install Guides
--------------
Install Guides are on the main `OpenStack Install Guide Site <https://docs.openstack.org/project-install-guide/dns/ocata/>`_
Upgrade Guides
--------------
Designate is a multi-tenant DNSaaS service for OpenStack. It provides a REST
API with integrated Keystone authentication. It can be configured to
auto-generate records based on Nova and Neutron actions. Designate supports
a variety of DNS servers including Bind9 and PowerDNS.
.. toctree::
:maxdepth: 1
upgrade/kilo
upgrade/mitaka
Install Guide <https://docs.openstack.org/project-install-guide/dns/ocata/>
API Reference <https://developer.openstack.org/api-ref/dns/>
Openstack CLI <https://docs.openstack.org/developer/python-designateclient/shell-v2.html>
getting-involved
devstack
support-matrix
backends
tempest
Designate in general
--------------------
.. toctree::
:maxdepth: 1
ops/operations-faq
backends
designate-manage
gmr
integrations
pools
production-guidelines
notifications
support-matrix
metrics
This documentation is generated by the Sphinx toolkit and lives in the `source tree`_.
Developer Documentation
=======================
@ -78,10 +27,69 @@ Developer Documentation
.. toctree::
:maxdepth: 1
sourcedoc
architecture
integrations
ubuntu-dev
devstack
tempest
gmr
sourcedoc
metrics
User Guide
==========
.. toctree::
:maxdepth: 1
:glob:
howtos/manage-ptr-records
howtos/secondary-zones
rest
Administration Guide
====================
.. toctree::
:maxdepth: 1
:glob:
pools
pool-scheduler
troubleshooting
howtos/multiple-pools
howtos/blacklists
howtos/tlds
howtos/quotas
designate-manage
notifications
production-guidelines
Upgrades
========
.. toctree::
:maxdepth: 1
upgrade/kilo
upgrade/mitaka
Other Modules
=============
.. toctree::
:maxdepth: 1
python-designateclient <https://docs.openstack.org/developer/python-designateclient/>
designate-dashboard <https://docs.openstack.org/developer/designate-dashboard/>
designate-tempest-plugin <https://docs.openstack.org/developer/designate-tempest-plugin/>
designate-specs <https://docs.openstack.org/developer/designate-specs/>
designate-msdnsagent <https://docs.openstack.org/developer/designate-msdnsagent/>
Other Resources
===============
.. toctree::
:maxdepth: 1
related
Indices and tables
@ -91,7 +99,4 @@ Indices and tables
* :ref:`modindex`
* :ref:`search`
.. _OpenStack Wiki: https://wiki.openstack.org/wiki/Designate
.. _source tree: https://git.openstack.org/cgit/openstack/designate

6
doc/source/metrics.rst

@ -1,8 +1,8 @@
.. _metrics:
*******
metrics
*******
****************************
Monasca-Statsd based Metrics
****************************
metrics Base
============

0
doc/source/pools/scheduler.rst → doc/source/pool-scheduler.rst

15
doc/source/pools.rst

@ -15,18 +15,9 @@
.. _pools:
=====
Pools
=====
Contents:
.. toctree::
:maxdepth: 2
:glob:
pools/scheduler
================
DNS Server Pools
================
Overview
========

6
doc/source/rest.rst

@ -1,8 +1,8 @@
.. _rest:
========================
REST API Documentation
========================
=================================
Deprecated REST API Documentation
=================================
Intro
=====

2
doc/source/sourcedoc.rst

@ -1,4 +1,4 @@
Source code documentation
Source Code Documentation
-------------------------
.. toctree::

17
doc/source/ops/operations-faq.rst → doc/source/troubleshooting.rst

@ -1,21 +1,20 @@
Operations FAQ
==============
Troubleshooting
===============
I have a broken zone
--------------------
A zone is considered broken when it is not receiving updates anymore. Its status can be "ERROR" if Designate detected the error condition or it can be stuck in "PENDING" for a long time.
Review the logs from the API, Central, Zone Manager, Pool Manager and MiniDNS.
Review the logs from the API, Central, Producer, Worker and MiniDNS.
Identify the transaction ID of the last successful change and the first failing change. Using the ID, you can filter logs from the Designate components that are related to the same transaction.
Look for log messages with ERROR level before and after the first failing update.
Failures in updating a zone are usually related to problems in Zone Manager, Pool Manager, MiniDNS or the database.
Failures in updating a zone are usually related to problems in Producer, Worker, MiniDNS or the database.
Ensure the services are running and network connectivity is not impaired.
Transient network issues can be the cause of a broken zone. Zone Manager and Pool Manager are stateful services and perform attempts at restoring failing zones over time. Restarting the services will trigger new attempts.
Transient network issues can be the cause of a broken zone. Producer and Worker are stateful services and perform attempts at restoring failing zones over time. Restarting the services will trigger new attempts.
I have a broken pool
@ -77,17 +76,17 @@ Central, MiniDNS
What needs access to RabbitMQ?
------------------------------
The API, Central, Zone Manager, Pool Manager, MiniDNS
The API, Central, Producer, Worker, MiniDNS
What needs access to ZooKeeper?
-------------------------------
Pool and Zone Manager
Pool and Producer
What needs access to Memcached?
-------------------------------
API and Pool Manager
API and Worker
How do I monitor Designate?
---------------------------