DNS zone management

Zones divide the DNS namespace into manageable segments that users can create, modify, delete, export, and import within their project.

The RHOSO DNS service (designate) uses a similar zone ownership model as DNS, with two major differences.

For example, in DNS, within the root zone (.) there are zones for each of the top level domains (TLDs) such as .org. and .com.. Within the TLD zones, there can be delegations to other zones, such as example.org. or example.com. that can be owned and managed by other organizations (or other sets of name servers). This example demonstrates a hierarchy of responsibility, with the higher-level zones composed mostly of delegations to the lower-level zones.

Similar to DNS, with the RHOSO DNS service, a zone can be owned by only one tenant. However, unlike DNS, the DNS service does not support zone delegation between tenants. That is, a tenant cannot create a child zone whose parent zone is owned by a different tenant.

The second difference between DNS and the RHOSO DNS service is that the DNS service manages TLDs differently than zones. The DNS service restricts tenants from creating zones that are not within a managed TLD. If the DNS service manages no TLDs, then tenants can create any TLD and any zone, other than the root zone.

Create a DNS zone for your domain
Copy link

Create a DNS zone to manage domain names and records within your project.

Before you begin
Copy link

  • The administrator has created a project for you and has provided you with a clouds.yaml file for you to access the cloud.
  • The python-openstackclient package is on your workstation. 
    $ dnf list installed python-openstackclient
  • Your RHOSO project must own the zone in which you are creating a sub-zone, or the zone must be an allowed TLD.

Procedure
Copy link

  1. Confirm that the system OS_CLOUD variable is set for your cloud: 
    $ echo $OS_CLOUD
my_cloud

    Reset the variable if necessary:

    $ export OS_CLOUD=my_other_cloud

    As an alternative, you can specify the cloud name by adding the --os-cloud <cloud_name> option each time you run an openstack command.

  2. Create a zone by specifying a name for the zone and an email address of the person responsible for the zone.
    Example
    $ openstack zone create --email dnsprimary@example.com example.com.

    When you create a zone, the DNS service automatically creates two record sets: an SOA record and an NS record.

Results
Copy link

  • Confirm that your zone exists by running the openstack zone list command.
    Sample output
    +--------------------------------------+--------------+---------+------------+--------+--------+
| id                                   | name         | type    |     serial | status | action |
+--------------------------------------+--------------+---------+------------+--------+--------+
| 14093115-0f0f-497a-ac69-42235e46c26f | example.com. | PRIMARY | 1468421656 | ACTIVE | NONE   |
+--------------------------------------+--------------+---------+------------+--------+--------+

Update a zone
Copy link

Modify zone properties such as the email address or TTL value.

Before you begin
Copy link

  • The administrator has created a project for you and has provided you with a clouds.yaml file for you to access the cloud.
  • The python-openstackclient package is on your workstation. 
    $ dnf list installed python-openstackclient
  • Your RHOSO project must own the zone that you are modifying.

Procedure
Copy link

  1. Confirm that the system OS_CLOUD variable is set for your cloud: 
    $ echo $OS_CLOUD
my_cloud

    Reset the variable if necessary:

    $ export OS_CLOUD=my_other_cloud

    As an alternative, you can specify the cloud name by adding the --os-cloud <cloud_name> option each time you run an openstack command.

  2. Modify the zone by specifying the name of the zone and the zone attributes that you want to change:
    --email <email_address>
    a valid email address for the person responsible (owner) for the zone.
    --ttl <seconds>
    (Time To Live) the duration, in seconds, that a DNS client—​for example, a resolver, a browser, an operating system—​can cache a record before checking to see if it has updated.
    --description <string> | --no-description
    a string that describes the purpose of the zone.
    --masters <dns-server> [<dns-server> …​]
    the fully qualified domain name for the DNS server that is the primary instance—​the instance that other DNS servers can sync from to become secondary servers.
    Example
    $ openstack zone set example.com. --ttl 3000

Results
Copy link

  • Confirm that your modification to the zone succeeded.
    Example
    $ openstack zone show example.com.

Remove a DNS zone
Copy link

You can delete a zone from the DNS service. For example, you would delete a zone when the zone name has changed.

Before you begin
Copy link

  • The administrator has created a project for you and has provided you with a clouds.yaml file for you to access the cloud.
  • The python-openstackclient package is on your workstation. 
    $ dnf list installed python-openstackclient
  • Your RHOSO project must own the zone that you are deleting.

Procedure
Copy link

  1. Confirm that the system OS_CLOUD variable is set for your cloud: 
    $ echo $OS_CLOUD
my_cloud

    Reset the variable if necessary:

    $ export OS_CLOUD=my_other_cloud

    As an alternative, you can specify the cloud name by adding the --os-cloud <cloud_name> option each time you run an openstack command.

  2. Delete the zone.
    Example
    $ openstack zone delete example.com.

Results
Copy link

  • Confirm that your zone no longer exists by running the openstack zone list command.

Export zones for backup or migration
Copy link

Export zone data for backup or migration purposes.

Before you begin
Copy link

  • The administrator has created a project for you and has provided you with a clouds.yaml file for you to access the cloud.
  • The python-openstackclient package is on your workstation. 
    $ dnf list installed python-openstackclient
  • Your RHOSO project must own the zone from which you are exporting data

Procedure
Copy link

  1. Confirm that the system OS_CLOUD variable is set for your cloud: 
    $ echo $OS_CLOUD
my_cloud

    Reset the variable if necessary:

    $ export OS_CLOUD=my_other_cloud

    As an alternative, you can specify the cloud name by adding the --os-cloud <cloud_name> option each time you run an openstack command.

  2. Export the zone.
    Example
    $ openstack zone export create example.com.
    Sample output
    +------------+--------------------------------------+
| Field      | Value                                |
+------------+--------------------------------------+
| created_at | 2022-02-11T02:01:30.000000           |
| id         | e75aef2c-b562-4cd9-a426-4a73f6cb82be |
| location   | None                                 |
| message    | None                                 |
| project_id | cf5a8f5cc5834d2dacd1d54cd0a354b7     |
| status     | PENDING                              |
| updated_at | None                                 |
| version    | 1                                    |
| zone_id    | d8f81db6-937b-4388-bfb3-ba620e6c09fb |
+------------+--------------------------------------+
    Important

    After you create a zone export resource, the DNS service continues to update the resource with any later changes that are made to the zone.
  3. Record the zone export ID (e75aef2c-b562-4cd9-a426-4a73f6cb82be), because you must use it to verify your zone export, and to access the zone export data.

Results
Copy link

  1. Confirm that the DNS service successfully created a zone export resource.
    Example
    $ openstack zone export show e75aef2c-b562-4cd9-a426-4a73f6cb82be
    Sample output
    +------------+--------------------------------------------------------------------------------+
| Field      | Value                                                                          |
+------------+--------------------------------------------------------------------------------+
| created_at | 2022-02-11T02:01:30.000000                                                     |
| id         | e75aef2c-b562-4cd9-a426-4a73f6cb82be                                           |
| location   | designate://v2/zones/tasks/exports/e75aef2c-b562-4cd9-a426-4a73f6cb82be/export |
| message    | None                                                                           |
| project_id | cf5a8f5cc5834d2dacd1d54cd0a354b7                                               |
| status     | COMPLETE                                                                       |
| updated_at | 2022-02-11T02:01:30.000000                                                     |
| version    | 2                                                                              |
| zone_id    | d8f81db6-937b-4388-bfb3-ba620e6c09fb                                           |
+------------+--------------------------------------------------------------------------------+

    The zone export create command creates a resource that the DNS service stores internally by default.

  2. Access the contents of the zone export file, by using the zone export ID that you obtained earlier. Tip

    Using the -f value option prints the contents of the zone file without any tabulation. You can also redirect the contents to a local text file, which can be useful if you want to modify the exported zone file locally and then import it back into the DNS service to update the zone.

    Example
    $ openstack zone export showfile e75aef2c-b562-4cd9-a426-4a73f6cb82be -f value
    Sample output
    $ORIGIN example.com.
$TTL 3600

example.com.  IN NS ns1.example.com.
example.com.  IN SOA ns1.example.com. admin.example.com. 1624414033 3583 600 86400 3600

www.example.com.  IN A 192.0.2.2
www.example.com.  IN A 192.0.2.1

Import zones for restore or migration
Copy link

Import zone data from a file to restore or migrate zones when you need to import zone data into your Red Hat OpenStack Services on OpenShift (RHOSO) DNS service. For example, a user accidentally deletes a zone.

Before you begin
Copy link

  • The administrator has created a project for you and has provided you with a clouds.yaml file for you to access the cloud.
  • The python-openstackclient package is on your workstation. 
    $ dnf list installed python-openstackclient
  • Your RHOSO project must own the zone in which you are creating a sub-zone, or the zone must be an allowed TLD.
  • The zone you are importing must not exist already.
  • The zone data that you are importing must contain a zone TTL (time to live) value.

Procedure
Copy link

  1. Confirm that the system OS_CLOUD variable is set for your cloud: 
    $ echo $OS_CLOUD
my_cloud

    Reset the variable if necessary:

    $ export OS_CLOUD=my_other_cloud

    As an alternative, you can specify the cloud name by adding the --os-cloud <cloud_name> option each time you run an openstack command.

  2. List the zones on your system: 
    $ openstack zone list
  3. If a the zone that you want to import already exists, you must delete it first by running the openstack zone delete command.
    Example
    $ openstack zone delete example.com.
  4. Confirm that your zone no longer exists by listing the zones on your system: 
    $ openstack zone list
  5. Confirm that the zone data you are planning to import contains a zone TTL value.
    Example
    $ cat /home/stack/zone_file
    Sample output
    $ORIGIN example.com.
$TTL 3000

example.com.  IN NS test.example.com.
example.com.  IN SOA test.example.com. admin.example.com. 1624415706 9000 500 86000 5000
www.example.com.  IN A 192.0.2.2
test.example.com.  IN NS test.example.com.
  6. Import a valid zone data file.
    Example
    $ openstack zone import create /home/stack/zone_file

Results
Copy link

  • Confirm that the DNS service successfully imported the zone.
    Example
    $ openstack recordset list -c name -c type -c records -c status example.com.
    Sample output
    +-------------------+------+-------------------------+--------+
| name              | type | records                 | status |
+-------------------+------+-------------------------+--------+
| example.com.      | SOA  | ns1.example.com. admin. | ACTIVE |
|                   |      | example.com. 1624415706 |        |
|                   |      | 3582 500 86000 3600     |        |
| test.example.com. | NS   | test.example.com.       | ACTIVE |
| example.com.      | NS   | ns1.example.com.        | ACTIVE |
| www.example.com.  | A    | 192.0.2.2               | ACTIVE |
+-------------------+------+-------------------------+--------+

Transfer zone ownership
Copy link

You can transfer the ownership of zones from one project to another project. For example, the finance team might want to transfer the ownership of the wow.example.com. zone from their project to a project in the sales team.

Before you begin
Copy link

  • The administrator has created a project for you and has provided you with a clouds.yaml file for you to access the cloud.
  • The python-openstackclient package is on your workstation. 
    $ dnf list installed python-openstackclient
  • Your project must own the zone that you want to transfer.
  • After you create the transfer request, a member of the receiving project must accept the zone that you are transferring.

About this task
Copy link

You can transfer ownership of zones without a cloud administrator’s involvement. However, both the current project zone owner and a member of the receiving project must agree on the transfer.

Procedure
Copy link

  1. Confirm that the system OS_CLOUD variable is set for your cloud: 
    $ echo $OS_CLOUD
my_cloud

    Reset the variable if necessary:

    $ export OS_CLOUD=my_other_cloud

    As an alternative, you can specify the cloud name by adding the --os-cloud <cloud_name> option each time you run an openstack command.

  2. Obtain the ID for the project to which you want to transfer ownership of the zone.
    Example
    $ openstack project list
    Sample output
    +----------------------------------+---------+
| ID                               | Name    |
+----------------------------------+---------+
| 7af0acba0486472da2447ff55df4a26d | Finance |
| 1d12e87fad0d437286c2873b36a12316 | Sales   |
+----------------------------------+---------+
  3. Using the project ID obtained in the previous step, create a zone transfer request for the zone that you want to transfer.
    Note

    When using a target project ID, no other project can accept the zone transfer. If you do not provide a target project ID, then any project that has the transfer request ID and its key can receive the zone transfer.
    Example

    To transfer the zone wow.example.com. to project 1d12e87fad0d437286c2873b36a12316, you run:

    $ openstack zone transfer request create \
--target-project-id 1d12e87fad0d437286c2873b36a12316 wow.example.com.
    Sample output
    +-------------------+-----------------------------------------------------+
| Field             | Value                                               |
+-------------------+-----------------------------------------------------+
| created_at        | 2022-05-26T22:06:39.000000                          |
| description       | None                                                |
| id                | 63cab5e5-65fa-4480-b26c-c16c267c44b2                |
| key               | BIFJIQWH                                            |
| links             | {'self': 'http://127.0.0.1:60053/v2/zones/tasks/tra |
|                   | nsfer_requests/63cab5e5-65fa-4480-b26c-c16c267c44b2 |
|                   | '}                                                  |
| project_id        | 6265985fc493465db6a978b318a01996                    |
| status            | ACTIVE                                              |
| target_project_id | 1d12e87fad0d437286c2873b36a12316                    |
| updated_at        | None                                                |
| zone_id           | 962f08b4-b671-4096-bf24-8908c9d4af0c                |
| zone_name         | wow.example.com.                                    |
+-------------------+-----------------------------------------------------+
  4. Obtain the zone transfer request ID and its key.
    Example
    $ openstack zone transfer request list -c id -c zone_name -c key
    Sample output
    +--------------------------------------+------------------+----------+
| id                                   | zone_name        | key      |
+--------------------------------------+------------------+----------+
| 63cab5e5-65fa-4480-b26c-c16c267c44b2 | wow.example.com. | BIFJIQWH |
+--------------------------------------+------------------+----------+
  5. Provide the zone transfer request ID and its key to a member of the receiving project.
  6. A member of the receiving project logs in to the receiving project, and sources his or her credentials file.
    Example
    $ source ~/overcloudrc
  7. Using the zone transfer request ID and its key, accept the zone transfer.
    Example
    $ openstack zone transfer accept request \
--transfer-id 63cab5e5-65fa-4480-b26c-c16c267c44b2 --key BIFJIQWH
    Sample output
    +--------------------------+----------------------------------------------+
| Field                    | Value                                        |
+--------------------------+----------------------------------------------+
| created_at               | 2022-05-27T21:37:43.000000                   |
| id                       | a4c4f872-c98c-411b-a787-58ed0e2dce11         |
| key                      | BIFJIQWH                                     |
| links                    | {'self': 'http://127.0.0.1:60053/v2/zones/ta |
|                          | sks/transfer_accepts/a4c4f872-c98c-411b-a787 |
|                          | -58ed0e2dce11', 'zone': 'http://127.0.0.1:60 |
|                          | 053/v2/zones/962f08b4-b671-4096-bf24-8908c9d |
|                          | 4af0c'}                                      |
| project_id               | 1d12e87fad0d437286c2873b36a12316             |
| status                   | COMPLETE                                     |
| updated_at               | 2022-05-27T21:37:43.000000                   |
| zone_id                  | 962f08b4-b671-4096-bf24-8908c9d4af0c         |
| zone_transfer_request_id | 63cab5e5-65fa-4480-b26c-c16c267c44b2         |
+--------------------------+----------------------------------------------+

Results
Copy link

  • Using the zone transfer accept ID from the previous step, check the status of your zone transfer.
    Example

    In this example, the zone status accept ID is a4c4f872-c98c-411b-a787-58ed0e2dce11.

    $ openstack zone transfer accept show a4c4f872-c98c-411b-a787-58ed0e2dce11
    Sample output
    +--------------------------+----------------------------------------------+
| Field                    | Value                                        |
+--------------------------+----------------------------------------------+
| created_at               | 2022-05-27T21:37:43.000000                   |
| id                       | a4c4f872-c98c-411b-a787-58ed0e2dce11         |
| key                      | None                                         |
| links                    | {'self': 'http://127.0.0.1:60053/v2/zones/ta |
|                          | sks/transfer_accepts/a4c4f872-c98c-411b-a787 |
|                          | -58ed0e2dce11', 'zone': 'http://127.0.0.1:60 |
|                          | 053/v2/zones/962f08b4-b671-4096-bf24-8908c9d |
|                          | 4af0c'}                                      |
| project_id               | 1d12e87fad0d437286c2873b36a12316             |
| status                   | COMPLETE                                     |
| updated_at               | 2022-05-27T21:37:43.000000                   |
| zone_id                  | 962f08b4-b671-4096-bf24-8908c9d4af0c         |
| zone_transfer_request_id | 63cab5e5-65fa-4480-b26c-c16c267c44b2         |
+--------------------------+----------------------------------------------+

Modify zone transfer requests
Copy link

The first step of transferring the ownership of zones from one project to another project is to create a zone transfer request. If you need to change or delete the zone transfer request, you can do so.

Before you begin
Copy link

  • The administrator has created a project for you and has provided you with a clouds.yaml file for you to access the cloud.
  • The python-openstackclient package is on your workstation. 
    $ dnf list installed python-openstackclient
  • Your project must own the zone whose transfer request you are modifying.

Procedure
Copy link

  1. Confirm that the system OS_CLOUD variable is set for your cloud: 
    $ echo $OS_CLOUD
my_cloud

    Reset the variable if necessary:

    $ export OS_CLOUD=my_other_cloud

    As an alternative, you can specify the cloud name by adding the --os-cloud <cloud_name> option each time you run an openstack command.

  2. Obtain the ID for the zone transfer request you are modifying.
    Example
    $ openstack zone transfer request list -c id -c zone_name
    Sample output
    +--------------------------------------+------------------+
| id                                   | zone_name        |
+--------------------------------------+------------------+
| 63cab5e5-65fa-4480-b26c-c16c267c44b2 | wow.example.com. |
+--------------------------------------+------------------+
  3. Using the zone transfer request ID obtained in the previous step, you can update a limited set of fields on zone transfer requests, such as the description and target project ID.
    Example
    $ openstack zone transfer request set --description "wow zone transfer" \
63cab5e5-65fa-4480-b26c-c16c267c44b2
    Sample output
    +-------------------+-----------------------------------------------------+
| Field             | Value                                               |
+-------------------+-----------------------------------------------------+
| created_at        | 2022-05-26T22:06:39.000000                          |
| description       | wow zone transfer                                   |
| id                | 63cab5e5-65fa-4480-b26c-c16c267c44b2                |
| key               | BIFJIQWH                                            |
| links             | {'self': 'http://127.0.0.1:60053/v2/zones/tasks/tra |
|                   | nsfer_requests/63cab5e5-65fa-4480-b26c-c16c267c44b2 |
|                   | '}                                                  |
| project_id        | 6265985fc493465db6a978b318a01996                    |
| status            | ACTIVE                                              |
| target_project_id | 1d12e87fad0d437286c2873b36a12316                    |
| updated_at        | 2022-05-27T20:52:08.000000                          |
| zone_id           | 962f08b4-b671-4096-bf24-8908c9d4af0c                |
| zone_name         | wow.example.com.                                    |
+-------------------+-----------------------------------------------------+
  4. Using the zone transfer request ID obtained in step 2, you can cancel a pending zone transfer, by deleting its zone transfer request.
    Example
    $ openstack zone transfer request delete 63cab5e5-65fa-4480-b26c-c16c267c44b2

    There is no output from the zone transfer request delete command. Confirm that the zone transfer request is removed by running the zone transfer request list command.