Merge "Add user doc for managing recordsets"
This commit is contained in:
Zuul
Gerrit Code Review
commit
ddbbd430df
@ -11,6 +11,7 @@ Contents:
|
||||
:maxdepth: 2
|
||||
|
||||
manage-zones
|
||||
manage-recordsets
|
||||
rest
|
||||
manage-ptr-records
|
||||
secondary-zones
|
||||
|
||||
214
doc/source/user/manage-recordsets.rst
Normal file
214
doc/source/user/manage-recordsets.rst
Normal 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
|
||||
Loading…
x
Reference in New Issue
Block a user