diff --git a/doc/source/images/Designate-Arch.png b/doc/source/images/Designate-Arch.png index b4c8cccc0..19ad8b9b8 100644 Binary files a/doc/source/images/Designate-Arch.png and b/doc/source/images/Designate-Arch.png differ diff --git a/doc/source/images/Designate-Arch.svg b/doc/source/images/Designate-Arch.svg new file mode 100644 index 000000000..6c5b94cfd --- /dev/null +++ b/doc/source/images/Designate-Arch.svg @@ -0,0 +1,898 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + Producer + + + + Central + DB + Neutron /Users + + + + + API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Worker + + Backend + + + CustomerFacing DNSServers + + + + + + Mini DNS + + diff --git a/doc/source/images/Designate-DNS-Integration.png b/doc/source/images/Designate-DNS-Integration.png new file mode 100644 index 000000000..d28c4b574 Binary files /dev/null and b/doc/source/images/Designate-DNS-Integration.png differ diff --git a/doc/source/images/Designate-DNS-Integration.svg b/doc/source/images/Designate-DNS-Integration.svg new file mode 100644 index 000000000..dcbabf506 --- /dev/null +++ b/doc/source/images/Designate-DNS-Integration.svg @@ -0,0 +1,1628 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + nameserver + + + + + Worker + + Backend + + + + + + API + + + + vm1 + + + + vm2 + + .cloud.example.org + + + + + + + record + + vm1.domain1.cloud.example.org + + 10.20.30.50.in-addr.arpa + .zone1.cloud.example.org + + + Mini DNS + + + + + + record + + vm2.domain2.cloud.example.org + + 60.70.80.10.in-addr.arpa + .zone2.cloud.example.org + + + + + 10.80.70.60 + + + Neutron + Nova + + + + + + + + + + + + SOA + + + + + + + + + + + + + + + + + Neutron will use theDesignate API to managerecords when ports arecreated and destroyed + + + 2 + + + + + + + + + Domains and namescan be associated withfloating ips, ports andnetworks in Neutron + + 1 + + + + The designate workerwill tell the nameserverto update its zoneinformation + + + + 3 + + + Both forward andreverse records arecreated in thenameserver + + + 5 + + + + The nameserver willrequest updated zoneinformation fromMini DNS + + + + 4 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 50.30.20.10 + + + + + + + + 192.168.12.13 + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/images/Designate-DNS-Overview.png b/doc/source/images/Designate-DNS-Overview.png new file mode 100644 index 000000000..c036f9fe7 Binary files /dev/null and b/doc/source/images/Designate-DNS-Overview.png differ diff --git a/doc/source/images/Designate-DNS-Overview.svg b/doc/source/images/Designate-DNS-Overview.svg new file mode 100644 index 000000000..8648e68f4 --- /dev/null +++ b/doc/source/images/Designate-DNS-Overview.svg @@ -0,0 +1,1218 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + record + + + record + + + + record + + + + record + + + + record + + + CNAME + + + nameserver + + + record + + + + record + + + + record + + + + record + + + + record + + + A + + NS records delegatezone authority toanother nameserver + + There are dozens ofother record types suchas MX, CNAME and A + + SOA records set theauthoritative serverfor the current zone + + The root zone + + + nameserver + + + record + + + + record + + + + record + + + + record + + + + record + + + MX + DNSThe Domain Name System + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + NS + + + + + record + + record + + root nameservers + + NS + + NS + + + + + + + + + + + . + .org + .com + nameserver + .openstack.org + + + + + + + diff --git a/doc/source/images/Designate-DNS-Resolvers.png b/doc/source/images/Designate-DNS-Resolvers.png new file mode 100644 index 000000000..61f15398a Binary files /dev/null and b/doc/source/images/Designate-DNS-Resolvers.png differ diff --git a/doc/source/images/Designate-DNS-Resolvers.svg b/doc/source/images/Designate-DNS-Resolvers.svg new file mode 100644 index 000000000..78f9d2111 --- /dev/null +++ b/doc/source/images/Designate-DNS-Resolvers.svg @@ -0,0 +1,1568 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + 2 + + + + record + + + record + + + NS + + The root zone + DNS + + + + recursiveresolver + that record isn't presentso it providesnameserver for .org + + + + RecursiveResolvers + + + recursive resolver queriesopenstack.org forcloud.openstack.org + + + openstack.org nameserverprovides the A record forcloud.openstack.org + + + 1 + + + + 2 + + + + 3 + + + + 4 + + + + 5 + + + + 6 + + + recursive resolver queriesroot nameservers forcloud.openstack.org + + 1 + + recursive resolver queries.org nameserver forcloud.openstack.org + + .org nameserver providesnameserver foropenstack.org + + + 3 + + + + 4 + + + + 5 + + + + 6 + + + query + + record + + + + + 0 + + + + 7 + + + A user queriesa recursive resolverfor the address ofcloud.openstack.org + + + + + + + + + record + + + + record + + + + record + + + + record + + + + record + + + A + .openstack.org + nameserver + + + + + + record + + + record + + + record + + + + record + + + + record + + nameserver + .org + root nameservers + . + + + + + + + + + + + + + + + + + + + NS + + + + diff --git a/doc/source/images/Designate-MultiZone.png b/doc/source/images/Designate-MultiZone.png deleted file mode 100644 index 642b8ca38..000000000 Binary files a/doc/source/images/Designate-MultiZone.png and /dev/null differ diff --git a/doc/source/images/Designate-PowerDNS-Detail.png b/doc/source/images/Designate-PowerDNS-Detail.png deleted file mode 100644 index 23d56a6c8..000000000 Binary files a/doc/source/images/Designate-PowerDNS-Detail.png and /dev/null differ diff --git a/doc/source/images/Designate-Simple.svg b/doc/source/images/Designate-Simple.svg deleted file mode 100644 index c6293b444..000000000 --- a/doc/source/images/Designate-Simple.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/doc/source/index.rst b/doc/source/index.rst index 13c11d20d..5bf64e04d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,6 +13,7 @@ Contents .. toctree:: :maxdepth: 1 + intro/index install/index contributor/index user/index diff --git a/doc/source/intro/index.rst b/doc/source/intro/index.rst new file mode 100644 index 000000000..32963b7da --- /dev/null +++ b/doc/source/intro/index.rst @@ -0,0 +1,188 @@ +.. + Copyright 2020 OpenStack Foundation + All Rights Reserved. + + 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. + +.. _introduction: + +========================= +Introduction to Designate +========================= + +Designate is an Open Source DNS-as-a-Service implementation and a part of the +OpenStack ecosystem of services for running clouds. In order to understand what +Designate can do and how it works, it's necessary to understand some of the +basics of DNS. + +.. index:: + double: introduction; brief + +.. _what-is-dns: + +What is DNS? +----------------------------- + +The Domain Name System (DNS) is a system for naming resources connected to a +network, and works by storing various types of *record*, such as an IP adress +associated with a domain name. In practice, this is implemented by +*authoritative name servers* which contain these records and *resolvers* which +query name servers for records. Names are divided up into a hierarchy of zones, +allowing different name servers to be responsible for separate groups of zones +by delegating responsibility using records. + +The root zone, which is simply ".", is comprised entirely of records delegating +various top level domains (TLDs) to other nameservers. The TLD name servers +will contain records for domains within their TLD, such as the *.com* +nameserver having an *example.com* record, as well as records that delegate +zones to other nameservers, for example *openstack.org* might have their own +nameserver so that they can then create *cloud.openstack.org*. + +| + +.. image:: ../images/Designate-DNS-Overview.png + :align: center + :width: 800 + +| + +*Resolvers* are often formed in two parts: a *stub* resolver which is often +merely a library on a user's computer, and a *recursive resolver* that will +perform queries against nameservers before returning the result to the user. +When searching for a domain, the resolver will start at the end of the domain +and work its way back to the beginning. + +For example in the diagram below, when searching for +cloud.openstack.org, it will start with the root nameserver ".", which will +reply with the location of the ".org" nameserver. The resolver can then contact +the ".org" nameserver to get the "openstack.org" nameserver and from there +finally get the "cloud.openstack.org" record and return it to the user. + +| + +.. image:: ../images/Designate-DNS-Resolvers.png + :align: center + :width: 800 + +| + +In order to make this more efficient, the results are cached on the resolver, +so after the first user has requested "cloud.openstack.org", the resolver can +return the cached result for subsequent requests. + +Further reading on DNS and how it works is available here: + - https://en.wikipedia.org/wiki/Domain_Name_System + +While the system itself is defined via RFCs such as this: + - https://tools.ietf.org/html/rfc1034 + +.. _introducing-designate: + +Introducing Designate +----------------------------- + +Designate is an OpenStack service that allows users and operators to manage DNS +records, names and zones via a REST API and can configure existing DNS name +servers to contain those records. Designate can also be configured by an +operator to integrate with both the OpenStack Network Service (Neutron) and +the Compute Service (Nova) so that records are automatically created when +floating IPs and compute instances are created respectively, and uses the +OpenStack Identity Service (Keystone) for user management. Since there are a +multitude of software implementations of the DNS name server, Designate has a +pluggable backend that can be configured to manage many of them, most notably +BIND9 and PowerDNS. + +.. _designate-architecture: + +Designate Architecture +----------------------------- + +Designate is comprised of several different services: the API, Producer, +Central, Worker and Mini DNS. It uses an oslo.db compatible database +to store state and data, and an oslo.messaging compatible message +queue to facilitate communication between services. +Multiple copies of all Designate services can be run in tandem to facilitate +high availability deployments, with the API process often sitting behind +load balancers. + +| + +.. image:: ../images/Designate-Arch.png + :align: center + :width: 800 + +| + +Neutron and other users of Designate only need to be able to access the API +server, while administrators should ensure the DNS Nameservers to be +configured are able to access Mini DNS from which to request updates. + +Below we can see a common deployment scenario: + +A user has created two +zones in Designate: *zone1.cloud.openstack.org* and +*zone2.cloud.openstack.org*. This will result in two new zones +being created on the Designate-managed nameserver with SOA records. + +The user then created two networks in Neutron: one private +network with *zone1.cloud.openstack.org* assigned to it, and one +public network with *zone2.cloud.openstack.org*. + +They have then created virtual machine +*vm1* in Nova, connected to the private network in Neutron and attached +to a floating IP, and the virtual machine *vm2* attached directly to +the public network. Each of these actions triggers a chain of events +that will cause Neutron to request Designate create records on behalf +of the user, with the end result being that records are created in +the authoritative nameserver mapping the vm names to domains along +with PTR records to allow reverse lookups. + +| + +.. image:: ../images/Designate-DNS-Integration.png + :align: center + +| + +More information about configuring Neutron to work with Designate can be +found in the Neutron documentation at +https://docs.openstack.org/neutron/latest/admin/config-dns-int-ext-serv.html + +.. _using-designate: + +Using Designate +----------------------------- + +Designate provides a REST API and that is commonly used by one of three +methods. The most common is to use the OpenStack client, a python command-line +tool with commands for interacting with OpenStack services. The documentation +for the OpenStack client is available at +https://docs.openstack.org/python-openstackclient/. +The +`designate plugin https://docs.openstack.org/python-designateclient/latest/` +for the OpenStack client needs to be installed as well: + +.. code-block:: console + + pip install python-openstackclient + pip install python-designateclient + +Another popular way to use Designate is via the OpenStack Dashboard, Horizon. +Administrators will need to add the +`Designate Horizon plugin https://opendev.org/openstack/designate-dashboard` +to the dashboard in order to enable Designate features. + +Finally, for python developers the aforementioned Designate plugin for +the OpenStack client which can be used as a python library. Other languages +may have bindings available from one of the third party +`SDKs https://wiki.openstack.org/wiki/SDKs` for OpenStack.