openstack
/
designate
Code Issues Proposed changes

Merge "Add user doc for managing recordsets"

This commit is contained in:
Zuul 2021-06-09 21:34:01 +00:00 committed by Gerrit Code Review
parent 5c60084f13 999abb0d92
commit ddbbd430df
2 changed files with 215 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/user/index.rst
View File

@ -11,6 +11,7 @@ Contents:
:maxdepth: 2 :maxdepth: 2
manage-zones manage-zones
manage-recordsets
rest rest
manage-ptr-records manage-ptr-records
secondary-zones secondary-zones

214
doc/source/user/manage-recordsets.rst Normal file
View File

@ -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