Chapter 7. Managing zones

The Red Hat OpenStack Platform (RHOSP) DNS service (designate) uses zones to break up the namespace into easily managed pieces. A user can create, modify, delete, export, and import zones provided that their RHOSP project owns the zone.

The topics included in this section are:

7.1. Zones in the DNS service

The Red Hat OpenStack Platform (RHOSP) 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 RHOSP 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 RHOSP 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.

7.2. Creating a zone

Zones enable you to more easily manage namespaces. By default, any user can create Red Hat OpenStack Platform (RHOSP) DNS service (designate) zones.

Prerequisites

  • Your RHOSP project must own the zone in which you are creating a sub-zone, or the zone must be an allowed TLD.

Procedure

  1. Source your credentials file.

    Example

    $ source ~/overcloudrc

  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.

Verification

  • 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   |
+--------------------------------------+--------------+---------+------------+--------+--------+

Additional resources

  • zone create in the Command Line Interface Reference
  • zone list in the Command Line Interface Reference

7.3. Updating a zone

There can be situations when you must update a zone managed by the Red Hat OpenStack Platform (RHOSP) DNS service (designate). For example, when you want to change the email address associated with the zone, or when you want to change the zone TTL (time to live) value. By default, any user can modify a zone.

Prerequisites

  • Your RHOSP project must own the zone that you are modifying.

Procedure

  1. Source your credentials file.

    Example

    $ source ~/overcloudrc

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

Verification

  • Confirm that your modification to the zone succeeded.

    Example

    $ openstack zone show example.com.

Additional resources

  • zone set in the Command Line Interface Reference
  • zone show in the Command Line Interface Reference

7.4. Deleting a zone

You can remove zones managed by the Red Hat OpenStack Platform (RHOSP) DNS service (designate). For example, you would delete a zone when the zone name has changed.

Prerequisites

  • Your RHOSP project must own the zone that you are deleting.

Procedure

  1. Source your credentials file.

    Example

    $ source ~/overcloudrc

  2. Delete the zone.

    Example

    $ openstack zone delete example.com.

Verification

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

Additional resources

  • zone delete in the Command Line Interface Reference
  • zone list in the Command Line Interface Reference

7.5. Exporting zones

Exporting zone data from the Red Hat OpenStack Platform (RHOSP) DNS service consists of creating a zone export resource that the DNS service stores internally by default. An example is, designate://v2/zones/tasks/exports/e75aef2c-b562-4cd9-a426-4a73f6cb82be/export. After you create the zone export data resource, you can then access its contents. Exporting zone data is a part of an overall backup strategy for protecting DNS information for your RHOSP deployment.

Prerequisites

  • Your RHOSP project must own the zone from which you are exporting data.

Procedure

  1. Source your credentials file.

    Example

    $ source ~/overcloudrc

  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.

Verification

  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

Additional resources

7.6. Importing zones

Importing zone data into the Red Hat OpenStack Platform (RHOSP) DNS service consists of running the openstack zone import command on a file that conforms to the DNS zone data file format, such as a file created from data produced by the openstack zone export showfile command. One reason to import data is when a user accidentally deletes a zone.

Prerequisites

  • Your RHOSP 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

  1. Source your credentials file.

    Example

    $ source ~/overcloudrc

  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

Verification

  • 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.example.com. 1624415706 3582 500 86000 3600  | ACTIVE |
| test.example.com. | NS   | test.example.com.                                                   | ACTIVE |
| example.com.      | NS   | ns1.example.com.                                                    | ACTIVE |
| www.example.com.  | A    | 192.0.2.2                                                           | ACTIVE |
+-------------------+------+---------------------------------------------------------------------+--------+

Additional resources

7.7. Transferring zone ownership

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.

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.

Prerequisites

  • 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.

Procedure

  1. Source your credentials file.

    Example

    $ source ~/overcloudrc

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

Verification

  • 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         |
+--------------------------+----------------------------------------------+

Additional resources

7.8. Modifying zone transfer requests

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.

Prerequisites

  • Your project must own the zone whose transfer request you are modifying.

Procedure

  1. Source your credentials file.

    Example

    $ source ~/overcloudrc

  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.

Additional resources