Add user doc for managing recordsets
Documentation targeted at member personas who wish to manage records. Change-Id: I5400cfe61b2608aa4a1b383f140ef71c2dc342f7
This commit is contained in:
parent
3bde7a843f
commit
999abb0d92
|
@ -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
|
||||||
|
|
|
@ -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…
Reference in New Issue