DNS Server Pools


In designate we support the concept of multiple “pools” of DNS Servers.

This allows operators to scale out their DNS Service by adding more pools, avoiding the scaling problems that some DNS servers have for number of zones, and the total number of records hosted by a single server.

This also allows providers to have tiers of service (i.e. the difference between GOLD vs SILVER tiers may be the number of DNS Servers, and how they are distributed around the world.)

In a private cloud situation, it allows operators to separate internal and external facing zones.

To help users create zones on the correct pool we have a “scheduler” that is responsible for examining the zone being created and the pools that are available for use, and matching the zone to a pool.

The filters are pluggable (i.e. operator replaceable) and all follow a simple interface.

The zones are matched using “zone attributes” and “pool attributes”. These are key: value pairs that are attached to the zone when it is being created, and the pool. The pool attributes can be updated by the operator in the future, but it will not trigger zones to be moved from one pool to another.


Currently the only zone attribute that is accepted is the pool_id attribute. As more filters are merged there will be support for dynamic filters.

Target vs. Nameserver

One thing that can be confusing about pools is the differentiation between a target and a nameserver. The target is where Designate will try to write the change, while a namserver is where Designate checks that the change exists.

A great example of this is bind’s stealth master system. In this configuration, there could be a stealth master that you configure as your target and a set of slaves pointed to that master as your nameservers. Designate will write to the master and then look for the changes on the slaves before considering the change active.

Another example would be where Designate uses an API backend such as DynDNS or even another Designate instance. In this situation, you will typically have a single target with a set of nameservers to test that meet your requirements.

Managing Pools

In mitaka we moved the method of updating pools to a CLI in designate-manage

There is a YAML file that defines the pool, and is used to load this information into the database.


- 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
    - 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.
    - host:
      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)
    - type: powerdns
      description: PowerDNS Database Cluster

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

      # PowerDNS Configuration options
        port: 53
        connection: 'mysql+pymysql://designate:password@'

  # Optional list of additional IP/Port's for which designate-mdns will send
  # DNS NOTIFY packets to
   - host:
     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_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

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 to pull zones via AXFR from Designate’s mini-DNS at 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.


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

Designate Manage Pools Command Reference

Update Pools Information

designate-manage pool update [options]

Input file (Default: /etc/designate/pools.yaml)


This will simulate what will happen when you run this command


Any Pools not listed in the config file will be deleted


Running with --delete can be extremely dangerous.
It will delete any pools that are not in the supplied YAML file, and any
zones that are in that Pool.
Before running with --delete we recommend operators run with
--delete --dry-run to view the outcome.

Generate YAML File

designate-manage pool generate_file [options]

YAML file output too (Default: /etc/designate/pools.yaml)

Generate YAML File from Liberty Config

designate-manage pool export_from_config [options]

YAML file output too (Default: /etc/designate/pools.yaml)