Merge "update doc index, add ops FAQ and notifications"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
586dc94f04
@ -65,7 +65,7 @@ The current implemented periodic tasks in zone manager include emitting dns.zone
|
||||
|
||||
Designate Sink
|
||||
-----------------------
|
||||
designate-sink is an optional service which listens for event notifications, such as compute.instance.create.end, handlers are available for Nova and Neutron. Notification events can then be used to trigger record creation & deletion.
|
||||
designate-sink is an optional service which listens for event :doc:`notifications`, such as compute.instance.create.end, handlers are available for Nova and Neutron. Notification events can then be used to trigger record creation & deletion.
|
||||
|
||||
The current sink implementations generate simple forward lookup A records, using a format specified in handler-nova configuration. Any field in the event notification can be used to generate a record.
|
||||
|
||||
|
||||
@ -5,95 +5,92 @@ Designate, a DNSaaS component for OpenStack
|
||||
Designate provides DNSaaS services for OpenStack:
|
||||
|
||||
* REST API for domain & record management
|
||||
* Multi-tenant
|
||||
* 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 & contributors of the project.
|
||||
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`_.
|
||||
|
||||
Install Guides
|
||||
==============
|
||||
General documentation
|
||||
=====================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
install/*
|
||||
|
||||
Upgrade Guides
|
||||
==============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
upgrade/*
|
||||
|
||||
User How To Guides
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
howtos/manage-domains
|
||||
|
||||
Admin How To Guides
|
||||
===================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
howtos/blacklists
|
||||
howtos/manage-ptr-records
|
||||
howtos/quotas
|
||||
howtos/tlds
|
||||
howtos/secondary-zones
|
||||
|
||||
Reference Documentation
|
||||
=======================
|
||||
New to Designate? Start here:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
architecture
|
||||
getting-involved
|
||||
developer-guidelines
|
||||
production-guidelines
|
||||
production-architecture
|
||||
configuration
|
||||
designate-manage
|
||||
rest
|
||||
devstack
|
||||
tempest
|
||||
related
|
||||
glossary
|
||||
backends
|
||||
integrations
|
||||
functional-tests
|
||||
gmr
|
||||
support-matrix
|
||||
pools
|
||||
memory-caching
|
||||
service_status
|
||||
|
||||
Source Documentation
|
||||
====================
|
||||
|
||||
User documentation
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
api
|
||||
backend
|
||||
central
|
||||
mdns
|
||||
objects
|
||||
quota
|
||||
sink
|
||||
storage
|
||||
howtos/*
|
||||
rest
|
||||
|
||||
Operations documentation
|
||||
========================
|
||||
|
||||
Install Guides
|
||||
--------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
install/ubuntu-kilo
|
||||
install/ubuntu-liberty
|
||||
|
||||
Upgrade Guides
|
||||
--------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
upgrade/*
|
||||
|
||||
Designate in general
|
||||
--------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ops/operations-faq
|
||||
backends
|
||||
configuration
|
||||
designate-manage
|
||||
gmr
|
||||
integrations
|
||||
memory-caching
|
||||
pools
|
||||
production-guidelines
|
||||
service_status
|
||||
notifications
|
||||
support-matrix
|
||||
|
||||
|
||||
Developer Documentation
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
getting-involved
|
||||
developer-guidelines
|
||||
sourcedoc
|
||||
install/ubuntu-dev
|
||||
devstack
|
||||
functional-tests
|
||||
tempest
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
71
doc/source/notifications.rst
Normal file
71
doc/source/notifications.rst
Normal file
@ -0,0 +1,71 @@
|
||||
Notifications
|
||||
=============
|
||||
|
||||
.. HINT::
|
||||
|
||||
In this context, "notifications" are not related to the DNS NOTIFY message.
|
||||
|
||||
|
||||
Notifications are RPC calls that contain a JSON object. Designate both generates and receives notifications.
|
||||
|
||||
The purpose of notifications in to inform unrelated OpenStack components of events in real time and trigger actions.
|
||||
|
||||
Emitters
|
||||
--------
|
||||
|
||||
They are emitted by Central on the following events:
|
||||
|
||||
* dns.tld.create
|
||||
* dns.tld.update
|
||||
* dns.tld.delete
|
||||
* dns.tsigkey.create
|
||||
* dns.tsigkey.update
|
||||
* dns.tsigkey.delete
|
||||
* dns.domain.create
|
||||
* dns.zone.create
|
||||
* dns.domain.update
|
||||
* dns.zone.update
|
||||
* dns.domain.delete
|
||||
* dns.zone.delete
|
||||
* dns.zone.touch
|
||||
* dns.recordset.create
|
||||
* dns.recordset.update
|
||||
* dns.recordset.delete
|
||||
* dns.record.create
|
||||
* dns.record.update
|
||||
* dns.record.delete
|
||||
* dns.blacklist.create
|
||||
* dns.blacklist.update
|
||||
* dns.blacklist.delete
|
||||
* dns.pool.create
|
||||
* dns.pool.update
|
||||
* dns.pool.delete
|
||||
* dns.domain.update
|
||||
* dns.zone.update
|
||||
* dns.zone_transfer_request.create
|
||||
* dns.zone_transfer_request.update
|
||||
* dns.zone_transfer_request.delete
|
||||
* dns.zone_transfer_accept.create
|
||||
* dns.zone_transfer_accept.update
|
||||
* dns.zone_transfer_accept.delete
|
||||
* dns.zone_import.create
|
||||
* dns.zone_import.update
|
||||
* dns.zone_import.delete
|
||||
* dns.zone_export.create
|
||||
* dns.zone_export.update
|
||||
* dns.zone_export.delete
|
||||
|
||||
Receivers
|
||||
---------
|
||||
|
||||
Notification from other OpenStack component outside of Designate are received by :ref:`designate-sink`.
|
||||
|
||||
Format
|
||||
------
|
||||
|
||||
An example notification from Neutron:
|
||||
|
||||
.. literalinclude:: ../../designate/tests/resources/sample_notifications/neutron/port.delete.start.json
|
||||
|
||||
More examples can be found at :file:`designate/tests/resources/sample_notifications`
|
||||
|
||||
117
doc/source/ops/operations-faq.rst
Normal file
117
doc/source/ops/operations-faq.rst
Normal file
@ -0,0 +1,117 @@
|
||||
Operations FAQ
|
||||
==============
|
||||
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
I have a broken pool
|
||||
--------------------
|
||||
|
||||
I deleted a zone but it's still in the database
|
||||
-----------------------------------------------
|
||||
|
||||
Deleted zones are flagged with "status" set to "DELETED" and "task" set to "NONE" once the deletion process terminates successfully.
|
||||
|
||||
What ports should be open?
|
||||
--------------------------
|
||||
|
||||
Port numbers are configurable: review your designate.conf
|
||||
|
||||
The default values are:
|
||||
|
||||
+------------------------+------------+----------+
|
||||
| Component | Protocol | Port |
|
||||
| (header rows optional) | | numbers |
|
||||
+========================+============+==========+
|
||||
| Agent | TCP | 5358 |
|
||||
+ +------------+----------+
|
||||
| | UDP | 5358 |
|
||||
+------------------------+------------+----------+
|
||||
| API | TCP | 9001 |
|
||||
+------------------------+------------+----------+
|
||||
| Keystone (external) | TCP | 35357 |
|
||||
+------------------------+------------+----------+
|
||||
| MiniDNS | TCP | 5354 |
|
||||
+ +------------+----------+
|
||||
| | UDP | 5354 |
|
||||
+------------------------+------------+----------+
|
||||
| MySQL | TCP | 3306 |
|
||||
+------------------------+------------+----------+
|
||||
| RabbitMQ | TCP | 5672 |
|
||||
+------------------------+------------+----------+
|
||||
| Resolvers | TCP | 53 |
|
||||
+ +------------+----------+
|
||||
| | UDP | 53 |
|
||||
+------------------------+------------+----------+
|
||||
| ZooKeeper | TCP | 2181 |
|
||||
+ +------------+----------+
|
||||
| | TCP | 2888,3888|
|
||||
+------------------------+------------+----------+
|
||||
|
||||
|
||||
|
||||
What network protocol are used?
|
||||
-------------------------------
|
||||
|
||||
HTTP[S] by the API, RabbitMQ and the MySQL protocol by most components, DNS (resolution and XFR), ZooKeeper, Memcached.
|
||||
|
||||
What needs access to the Database?
|
||||
----------------------------------
|
||||
|
||||
Central, MiniDNS
|
||||
|
||||
What needs access to RabbitMQ?
|
||||
------------------------------
|
||||
|
||||
The API, Central, Zone Manager, Pool Manager, MiniDNS
|
||||
|
||||
What needs access to ZooKeeper?
|
||||
-------------------------------
|
||||
|
||||
Pool and Zone Manager
|
||||
|
||||
What needs access to Memcached?
|
||||
-------------------------------
|
||||
|
||||
API and Pool Manager
|
||||
|
||||
How do I monitor Designate?
|
||||
---------------------------
|
||||
|
||||
Designate can be monitored by various `monitoring systems listed here <https://wiki.openstack.org/wiki/Operations/Monitoring>`_
|
||||
|
||||
OpenStack recommends `Monasca <https://wiki.openstack.org/wiki/Monasca>`_
|
||||
|
||||
What are useful metrics to monitor?
|
||||
-----------------------------------
|
||||
|
||||
* General host monitoring, i.e. CPU load, memory usage, disk and network I/O
|
||||
* MySQL performance, errors and free disk space
|
||||
* Number of zones in ACTIVE, PENDING and ERROR status
|
||||
* API queries per second, broken down by "read" and "write" operation on zones, records, etc
|
||||
* Zone change propagation time i.e. how long does it takes for a record update to reach the resolvers
|
||||
* Log messages containing having "ERROR" level
|
||||
* Quotas utilization i.e. number of existing records/zones against the maximum allowed
|
||||
* Memcached, RabbitMQ, ZooKeeper performance and errors
|
||||
|
||||
|
||||
What are useful metrics to review first during an incident?
|
||||
-----------------------------------------------------------
|
||||
|
||||
* Host, network and MySQL performance metrics
|
||||
* Number of zones in ACTIVE, PENDING and ERROR status
|
||||
* Log messages containing having "ERROR" level
|
||||
15
doc/source/sourcedoc.rst
Normal file
15
doc/source/sourcedoc.rst
Normal file
@ -0,0 +1,15 @@
|
||||
Source code documentation
|
||||
-------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
sourcedoc/api
|
||||
sourcedoc/backend
|
||||
sourcedoc/central
|
||||
sourcedoc/mdns
|
||||
sourcedoc/objects
|
||||
sourcedoc/quota
|
||||
sourcedoc/sink
|
||||
sourcedoc/storage
|
||||
|
||||
Loading…
Reference in New Issue
Block a user