# Pool Scheduler Filters

## About Filters

When a user creates a zone, the pool scheduler uses filters to assign the zone to a particular DNS server pool. As the administrator, you choose an ordered list of filters that runs on each `zone create` API request. You configure the scheduler to use filters that are provided with Designate or create your own.

## Filters Provided with Designate

Designate provides several filters that represent common use cases.

### Base Class - Filter

class designate.scheduler.filters.base.Filter(storage)

  This is the base class used for filtering Pools.

  This class should implement a single public function `filter()` which accepts a `designate.objects.pool.PoolList` and returns a `designate.objects.pool.PoolList`

  abstractmethod filter(context, pools, zone)

    Filter list of supplied pools based on attributes in the request

    Parameters:

      - context – `designate.context.DesignateContext` - Context Object from request

      - pools – `designate.objects.pool.PoolList` - List of pools to choose from

      - zone – `designate.objects.zone.Zone` - Zone to be created

    Returns:

      `designate.objects.pool.PoolList` - Filtered list of Pools

### Attribute Filter

class designate.scheduler.filters.attribute_filter.AttributeFilter(storage)

  Bases: `Filter`

  This allows users to choose the pool by supplying hints to this filter. These are provided as attributes as part of the zone object provided at zone create time.

      {
          "attributes": {
              "pool_level": "gold",
              "fast_ttl": "true",
              "pops": "global",
          },
          "email": "user@example.com",
          "name": "example.com."
      }

  The zone attributes are matched against the potential pool candidates, and any pools that do not match all hints are removed.

  Warning

  This should be uses in conjunction with the `designate.scheduler.impl_filter.filters.random_filter.RandomFilter` in case of multiple Pools matching the filters, as without it, we will raise an error to the user.

  name = 'attribute'

    Name to enable in the `[designate:central:scheduler].filters` option list

### Pool ID Attribute Filter

class designate.scheduler.filters.pool_id_attribute_filter.PoolIDAttributeFilter(storage)

  Bases: `Filter`

  This allows users with the correct role to specify the exact pool_id to schedule the supplied zone to.

  This is supplied as an attribute on the zone

      {
          "attributes": {
              "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842"
          },
          "email": "user@example.com",
          "name": "example.com."
      }

  The pool is loaded to ensure it exists, and then a policy check is performed to ensure the user has the correct role.

  Warning

  This should only be enabled if required, as it will raise a 403 Forbidden if a user without the correct role uses it.

  filter(context, pools, zone)

    Attempt to load and set the pool to the one provided in the Zone attributes.

    Parameters:

      - context – `designate.context.DesignateContext` - Context Object from request

      - pools – `designate.objects.pool.PoolList` - List of pools to choose from

      - zone – `designate.objects.zone.Zone` - Zone to be created

    Returns:

      `designate.objects.pool.PoolList` – A PoolList with containing a single pool.

    Raises:

      Forbidden, PoolNotFound

  name = 'pool_id_attribute'

    Name to enable in the `[designate:central:scheduler].filters` option list

### Random Filter

class designate.scheduler.filters.random_filter.RandomFilter(storage)

  Bases: `Filter`

  Randomly chooses one of the input pools if there are multiple ones supplied.

  Note

  This should be used as one of the last filters, as it reduces the supplied pool list to one.

  name = 'random'

    Name to enable in the `[designate:central:scheduler].filters` option list

### Fallback Filter

class designate.scheduler.filters.fallback_filter.FallbackFilter(storage)

  Bases: `Filter`

  If there is no zones available to schedule to, this filter will insert the default_pool_id.

  Note

  This should be used as one of the last filters, if you want to preserve behavior from before the scheduler existed.

  name = 'fallback'

    Name to enable in the `[designate:central:scheduler].filters` option list

### Default Pool Filter

class designate.scheduler.filters.default_pool_filter.DefaultPoolFilter(storage)

  Bases: `Filter`

  This filter will always return the default pool specified in the designate config file

  Warning

  This should be used as the only filter, as it will always return the same thing - a `designate.objects.pool.PoolList` with a single `designate.objects.pool.Pool`

  name = 'default_pool'

    Name to enable in the `[designate:central:scheduler].filters` option list

### In Doubt Default Pool Filter

class designate.scheduler.filters.in_doubt_default_pool_filter.InDoubtDefaultPoolFilter(storage)

  Bases: `Filter`

  If the previous filter(s) didn’t make a clear selection of one pool and if the default pool is in the set of multiple pools, this filter will select the default pool.

  This filter will pass through the pool list, if there are one or less pools available to schedule to, or if the default pool is not in the set of multiple pools.

  Note

  This should be used as one of the last filters.

  name = 'in_doubt_default_pool'

    Name to enable in the `[designate:central:scheduler].filters` option list

## Creating Custom Filters

You can create your own filters by extending `designate.scheduler.filters.base.Filter` and registering a new entry point in the `designate.scheduler.filters` namespace in `designate.conf`:

    [entry_points]
    designate.scheduler.filters =
    my_custom_filter = my_extension.filters.my_custom_filter:MyCustomFilter

## Configuring Filters in the Scheduler

After you have decided whether to use the filters provided with Designate or create custom filters you must configure the filters in the pool scheduler.

Inside the `designate.conf` file under the `[service:central]` section, add the filters that you want the scheduler to use to the `scheduler_filters` parameter:

    [service:central]
    scheduler_filters = attribute, pool_id_attribute, fallback, random, my_custom_filter

Important

The scheduler runs the filters list from left to right.

this page last updated: 2026-08-19 02:25:39

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