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

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