# DNS Server Pools

## About Pools

Administrators can group DNS namespace servers into multiple pools to help them manage their DNS environments. You can provide users with tiers of service, by configuring pools to offer more capacity and better geographical proximity. Administrators of private clouds can leverage multiple pools to separate internal and external facing zones.

By default, Designate contains only one DNS server pool called `default`. When users create a zone in a multi-pool environment, the pool scheduler must select a pool to host the new zone. Administrators control pool selection through the use of filters, that the scheduler uses to select a pool for the new zone.

The filter interface consists of pool attributes that are key-value pairs that the scheduler attaches to the zone during creation. Administrators can update pool attributes later, but none of the updates will trigger zones to move to another pool. Zones can be moved manually to a different pool, as mentioned in the API Reference.

Designate provides a set of filters that reflect some common use cases and also a simple interface that administrators can use to create custom filters.

## Process Overview for Configuring Multiple Pools

The process of configuring multiple DNS server pools in Designate, consists of the following steps:

1. Define the new pool in the pool definition file.

2. Load the new pool definition into the Designate database by running the `designate-manage` command.

3. Configure the pool scheduler to use one or more filters to match any new zones that users create with the appropriate pool. You can choose filters that are provided with Designate, or create new filters.

4. Supply the required pool information to users to specify when they create zones.

## Pool Definition File

A pool definition file is required when you create a DNS server pool in Designate. The required key value pairs in YAML format are documented here:

    ---

    - name: default
      # The name is immutable. There will be no option to change the name after
      # creation and the only way will to change it will be to delete it
      # (and all zones associated with it) and recreate it.
      description: Default PowerDNS Pool

      # Attributes are Key:Value pairs that describe the pool. for example the level
      # of service (i.e. service_tier:GOLD), capabilities (i.e. anycast: true) or
      # other metadata. Users can use this information to point their zones to the
      # correct pool
      attributes: {}

      # List out the NS records for zones hosted within this pool
      ns_records:
        - hostname: ns1-1.example.org.
          priority: 1
        - hostname: ns1-2.example.org.
          priority: 2

      # List out the nameservers for this pool. These are the actual PowerDNS
      # servers. We use these to verify changes have propagated to all nameservers.
      nameservers:
        - host: 192.0.2.2
          port: 53

      # List out the targets for this pool. For PowerDNS, this is the database
      # (or databases, if you deploy a separate DB for each PowerDNS server)
      targets:
        - type: powerdns
          description: PowerDNS Database Cluster

          # List out the designate-mdns servers from which PowerDNS servers should
          # request zone transfers (AXFRs) from.
          masters:
            - host: 192.0.2.1
              port: 5354

          # PowerDNS Configuration options
          options:
            host: 192.0.2.2
            port: 53
            connection: 'mysql+pymysql://designate:password@127.0.0.1/designate_pdns?charset=utf8'

      # Optional list of additional IP/Port's for which designate-mdns will send
      # DNS NOTIFY packets to
      also_notifies:
       - host: 192.0.2.4
         port: 53

      # Optional configuration to provide a catalog zone for the pool's zones.
      # If configured, catalog_zone_fqdn is required and all other keys are
      # optional.
      catalog_zone:
          catalog_zone_fqdn: cat.example.org.
          catalog_zone_refresh: 60
          # TSIG secret and algorithm to use for securing AXFRs for catalog zones.
          catalog_zone_tsig_key: SomeSecretKey
          catalog_zone_tsig_algorithm: hmac-sha512

### Pools.yaml attributes

#### NS records

The ns_records section is the list of name servers Designate will advertise in the zones as available for query. Nameservers listed in the ns_records section are expected to be advertised from external networks.

#### Nameservers

The nameservers section is the list of name servers Designate will query to confirm an update has completed on all of the Designate managed nameservers. Nameservers listed in the nameservers section are not expected to be advertised from external networks unless they are also listed in the ns_records section.

#### NS Records vs. Nameservers: Understanding the Differences

There isn’t always a direct relationship between the ns_records and the nameservers sections, as they serve different use cases. Here are a few use cases:

- ns_records list is equal to the nameservers list:

    The end user may want to query all of the advertised nameservers to confirm that their updates have successfully propagated.

- ns_records list is smaller than the nameservers list:

    The end user may have some private, or stealth, nameservers that they do not want to advertise publicly as ns_records. Because they are private, these stealth nameservers are not expected be necessarily reachable from external networks.

- ns_records list is larger than the nameservers list:

    The end user may not want to query all of the nameservers they manage after a zone update as some of those nameservers might be backup, or maybe the list of nameservers is just too big to query all of them.

#### Targets

The targets section defines how Designate should communicate with the backend nameservers and how those backend nameservers should communicate with MiniDNS. For the BIND driver, the options section defines the address and port the “NOTIFY” messages should go to and the IP:port the driver should use to make rndc calls to BIND, as can be seen in this example. PowerDNS require using the connection keyword, as can be seen above.

#### Catalog zones

Catalog zones provide easy provisioning capabilities of zones to secondary nameservers, transferred via AXFR from a special zone, the catalog zone.

In Designate, catalog zones are configured per pool. A catalog zone will include all zones from the pool (except the catalog zone itself), called member zones. That means all zones from that pool are automatically synced to secondary name servers upon zone creation, update or deletion. For more details about catalog zones, see RFC 9432.

Catalog zones can be configured in `pools.yaml` via the catalog_zone key (see the sample above). This example instructs a PowerDNS server listening at `192.0.2.2:53` to pull zones via AXFR from Designate’s `mini-DNS` at `192.0.2.1:5354`. Note that the secondary nameserver also needs to be properly configured to consume the catalog zone. Please refer to the secondary nameserver’s documentation for details. Once this is set up and applied using `designate-manage pool update`, Designate will handle the catalog zone creation as well as synchronization of member zones.

As secondary nameservers configure their zones based on zone transfers (AXFR) from the catalog zone, it is highly recommended to use transaction signatures (TSIG) for secure and authenticated zone transfers. See the above sample for details on how to use catalog zones with TSIG.

Warning

Even though not mandatory, it is highly recommended to secure transfers of
catalog zones with TSIG.

## designate-manage pool Command Reference

You manage pools in Designate with the `designate-manage pool` commands.

Note

Control plane does not need to be restarted after designate-manage pool command changes.

### Pool update

You manage can modify the current deployed pools with the `designate-manage pool update` command.

    designate-manage pool update [options]

#### Pool update options

`--file <file>`

  Input file. When a file is not specified, `/etc/designate/pools.yaml` is used by default.

`--dry-run`

  Simulates what happens when you run this command.

`--delete`

  Removes all pools not listed in the config file.

Warning

Using `--delete` can be extremely dangerous, because `designate-manage` removes any pools that are not in the supplied YAML file, including the default one and any zones that are in those pools. Before using `--delete`, use `--delete --dry-run` to view the outcome.

### Generating a Copy of the Pool Configuration

    designate-manage pool generate_file [options]

#### Options

`--file <file>`

  The YAML file where `designate-manage` writes its output. When a file is not specified, `designate-manage` writes to `/etc/designate/pools.yaml`.

### Showing the current Pools Configuration

    designate-manage pool show_config [options]

#### Options

`--pool_id <pool_id>`

  ID of the pool to be examined.

`--all_pools`

  Show the config of all the pools.

this page last updated: 2026-04-13 15:37:16

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug