From 999abb0d925b3c97274b0d0f116e3fff9cdf35df Mon Sep 17 00:00:00 2001 From: Michael Chapman Date: Fri, 30 Apr 2021 13:09:35 +1000 Subject: [PATCH] Add user doc for managing recordsets Documentation targeted at member personas who wish to manage records. Change-Id: I5400cfe61b2608aa4a1b383f140ef71c2dc342f7 --- doc/source/user/index.rst | 1 + doc/source/user/manage-recordsets.rst | 214 ++++++++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 doc/source/user/manage-recordsets.rst diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 4538ee628..507d0b82f 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -11,6 +11,7 @@ Contents: :maxdepth: 2 manage-zones + manage-recordsets rest manage-ptr-records secondary-zones diff --git a/doc/source/user/manage-recordsets.rst b/doc/source/user/manage-recordsets.rst new file mode 100644 index 000000000..71b4b52fa --- /dev/null +++ b/doc/source/user/manage-recordsets.rst @@ -0,0 +1,214 @@ +.. + Copyright 2021 Red Hat + + 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. + + +==================== + Managing Records +==================== + +While zones are used to break up the DNS namespace into a hierarchy, +'resource records', or simply 'records', are used to store data within the +namespace. Each record has a + +- **Name:** the string that indicates its location in the DNS namespace. +- **Type:** the set of `letter codes`_ that identify the record's usage. For + example ``A`` for an address record or ``CNAME`` for a canonical name record. +- **Class:** the set of letter codes that specify the namespace for the + record. Typically, this is ``IN`` for internet, though other namespaces do + exist. +- **TTL:** the duration in seconds that the record remains valid. +- **Rdata:** the data for the record, such as an IP address for an ``A`` type + record or another record name for a ``CNAME`` type record. + +Recordsets in Designate +======================= + +DNS records in Designate are managed using ``Recordsets``, which represent one +or more DNS records with the same `Name` and `Type`, but potentially different +data. For example, a recordset named ``www.example.com``, with a type of ``A``, +that contains the data ``192.0.2.1`` and ``192.0.2.2`` might reflect two web +servers hosting ``www.example.com`` located at those two IP addresses. + +You must create Recordsets within a zone. If you delete a zone that contains +recordsets, those recordsets within the zone are also deleted. + +Creating a recordset +-------------------- + +By default, any user can create Recordsets in zones that their project owns. +In this example, a user has created a zone named ``example.org.``. + +Recordsets are created using the ``openstack recordset create`` command and +require a zone, a name, a type, and data for the record. +To recreate the earlier example using the OpenStack client with the Designate +plugin, the user would run: + + + .. code-block:: console + + $ openstack recordset create --type A --record 192.0.2.1 example.org. www + +-------------+--------------------------------------+ + | Field | Value | + +-------------+--------------------------------------+ + | action | CREATE | + | created_at | 2021-05-03T03:13:46.000000 | + | description | None | + | id | 549c3e83-443f-474b-b467-6bcd7cb9f37d | + | name | www.example.org. | + | project_id | c85fdba96041438fa0cad2dc7909d3f5 | + | records | 192.0.2.1 | + | status | PENDING | + | ttl | None | + | type | A | + | updated_at | None | + | version | 1 | + | zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 | + | zone_name | example.org. | + +-------------+--------------------------------------+ + +As the final argument ``www`` is not a fully qualified domain name (FQDN) it +is prepended to the zone name. You can achieve the same result using the FQDN, +``www.example.org.``. Note that the trailing ``.`` is required when using the +FQDN. Omitting it results in the name, ``"www.example.org.example.org."``. + +You can supply the ``--record`` argument multiple times to create multiple +records within the recordset. A typical use for this is `Round-robin DNS`_. + + + .. code-block:: console + + $ openstack recordset create --type A --record 192.0.2.1 --record 192.0.2.2 example.org. web + +-------------+--------------------------------------+ + | Field | Value | + +-------------+--------------------------------------+ + | action | CREATE | + | created_at | 2021-05-03T03:26:43.000000 | + | description | None | + | id | 9e0fba43-ca67-44ed-b9d9-fc1242920319 | + | name | web.example.org. | + | project_id | c85fdba96041438fa0cad2dc7909d3f5 | + | records | 192.0.2.1 | + | | 192.0.2.2 | + | status | PENDING | + | ttl | None | + | type | A | + | updated_at | None | + | version | 1 | + | zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 | + | zone_name | example.org. | + +-------------+--------------------------------------+ + +You can view the recordsets for a zone using the ``openstack recordset list`` +command: + + .. code-block:: console + + $ openstack recordset list example.org. + +--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+ + | id | name | type | records | status | action | + +--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+ + | 3bebbd03-07d7-4274-a784-39c32a2be8c6 | example.org. | SOA | ns1.example.net. admin.example.org. 1620012616 3599 600 86400 3600 | ACTIVE | NONE | + | 7d34e4d3-a2f1-4af0-831c-ba52a8312c6a | example.org. | NS | ns1.example.net. | ACTIVE | NONE | + | 9e0fba43-ca67-44ed-b9d9-fc1242920319 | web.example.org. | A | 192.0.2.1 | ACTIVE | NONE | + | | | | 192.0.2.2 | | | + | 549c3e83-443f-474b-b467-6bcd7cb9f37d | www.example.org. | A | 192.0.2.1 | ACTIVE | NONE | + +--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+ + +The ``SOA`` and ``NS`` records for the zone are also visible here, but cannot +be modified. + +The authoritative nameserver for the zone is listed as the record data for the +``NS`` type record of the zone, which in this example is ``ns1.example.net.``. +To verify this you can query the nameserver using ``dig`` for the ``NS`` type: + + .. code-block:: console + + $ dig @ns1.example.net example.org. -t NS +short + ns1.devstack.org. + +You can also verify the ``A`` recordsets. You don't need the ``-t`` option +because it is the default: + + .. code-block:: console + + $ dig @ns1.example.net web.example.org. +short + 192.0.2.2 + 192.0.2.1 + $ dig @ns1.example.net www.example.org. +short + 192.0.2.1 + +Updating a recordset +-------------------- + +You can modify a recordset by using the ``openstack recordset set`` command. +When updating a recordset by name, you must use the FQDN. As with most +OpenStack commands, you can also use recordset ID. For example, to update +the recordset ``www.example.org.`` to contain two records, you could use +the following: + + .. code-block:: console + + $ openstack recordset set example.org. www.example.org. --record 192.0.2.1 --record 192.0.2.2 + +-------------+--------------------------------------+ + | Field | Value | + +-------------+--------------------------------------+ + | action | UPDATE | + | created_at | 2021-05-03T03:30:16.000000 | + | description | None | + | id | 549c3e83-443f-474b-b467-6bcd7cb9f37d | + | name | www.example.org. | + | project_id | c85fdba96041438fa0cad2dc7909d3f5 | + | records | 192.0.2.2 | + | | 192.0.2.1 | + | status | PENDING | + | ttl | None | + | type | A | + | updated_at | 2021-05-03T03:44:16.000000 | + | version | 5 | + | zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 | + | zone_name | example.org. | + +-------------+--------------------------------------+ + +Deleting a recordset +-------------------- + +You can use the ``openstack recordset delete`` command to remove recordsets +using the zone and either the FQDN or the recordset ID. + + .. code-block:: console + + $ openstack recordset delete example.org. web.example.org. + +-------------+--------------------------------------+ + | Field | Value | + +-------------+--------------------------------------+ + | action | DELETE | + | created_at | 2021-05-03T03:47:00.000000 | + | description | None | + | id | 5ab3418f-5377-47eb-b967-9e9ff7f3c26b | + | name | web.example.org. | + | project_id | c85fdba96041438fa0cad2dc7909d3f5 | + | records | 192.0.2.1 | + | | 192.0.2.2 | + | status | PENDING | + | ttl | None | + | type | A | + | updated_at | 2021-05-03T03:47:13.000000 | + | version | 2 | + | zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 | + | zone_name | example.org. | + +-------------+--------------------------------------+ + +.. _letter codes: https://en.wikipedia.org/wiki/List_of_DNS_record_types +.. _Round-robin DNS: https://en.wikipedia.org/wiki/Round-robin_DNS