Dynamic Zone Config

Dynamic zone configuration is a powerful tool for reducing the configuration required to run octoDNS, specifically the zones section. Rather than an exhaustive list of every zone and its corresponding sources and targets it’s possible to define the pattern once with a wildcard.

This is most commonly done with a YamlProvider which will result in building the list of zones managed at runtime from the yaml zone files in it’s directory, but any provider that supports the octodns.provider.yaml.YamlProvider.list_zones() method can be used.

Any zone name configured in the zones section with a leading * is considered dynamic and the information in this document applies. It is possible to include multiple dynamic zone configurations in advanced setups utilizing distinct sources and/or carefully crafted matching as described below.

Matching

There are three types of matching supported: legacy, file-glob, and regular expression. This ultimately results in very flexible and powerful options, but makes it pretty easy to build a foot-gun. The matching process has thorough info and debug logging that can be enabled with –debug and should be the first step in debugging a dynamic zone configuration.

Legacy

This is the default mode and the only one supported in versions prior to 1.14.0. It is in effect a catch-all in that any zones returned by the sources’ octodns.provider.yaml.YamlProvider.list_zones().

This generally means that it only makes sense to have multiple legacy matchers when they have distinct sources, otherwise the first one configured will claim all the zones leaving nothing available.

File-glob

This mode uses Unix shell style matching using the fnmatch module and is generally the place to start when trying to apply configs to zones in a single source or set of sources as it’s relatively easy to understand and predict the behavior of it.

A public and private setup where the public zones are also pushed internally is a good starting example. If the following zone YAML files are in the config provider’s directory:

company.com.
foundation.org
internal.net.
jobs.company.com.
other.com
support.company.com.
us-east-1.internal.net.
us-west-2.internal.net.

The following octoDNS configuration would match them as described in comments:

---
...

zones:

  # the names here do not really matter beyond starting with a *, it is a
  # recommended best practice to match the glob, but not required. It will be
  # used in logging to aid in debugging.

  # they are applied in the order defined and once claimed a zone is no
  # longer available for matching

  # everything is available for matching
  '*internal.net':
    # we only want the private zones here and they are all under
    # internet.net. so this glob will claim them.
    glob: '*internal.net.'
    sources:
      - config
    targets:
      # only push it to the private provider
      - private

  # legacy style match everything that's left, all our various public zones
  '*':
    # legacy style match everything that's left, all our various public zones
    sources:
      - config
    targets:
      # push it to the public dns
      - public
      # and private
      - private

This does mean that things are public by default so care would need to be taken if a new internal zone naming pattern is added.

Added in version 1.14.0: File-glob matching support was added in 1.14.0

Regular Expression

Regular expression mode works similarly to File-glob with the matching performed by the python regular expression engine re. It enables much more complex and powerful matching logic with the trade-off of having to work with regular expressions.

Continuing on with the public/private split, adding in the wrinkles of multiple internal domain names and the desire to split the regions pushing only to the co-located DNS servers. All of our internal zones end in .net., anything else is public:

company.com.
foundation.org
jobs.company.com.
other.com
support.company.com.
us-east-1.hosts.net.
us-east-1.network.net.
us-east-1.services.net.
us-west-2.hosts.net.
us-west-2.network.net.
us-west-2.services.net.

The following octoDNS configuration would match them as described in comments:

---
...

zones:

  # regexes are too ugly to use as names, so these have useful info for
  # logging/debugging

  # everything is available for matching
  '*us-east-1':
    # we only want the private zones here and they are all under
    # internet.net. So this regex will claim them, yes this could be done
    # with a glob, but ...
    regex: '^.*us-east-1.*.net.$'
    sources:
      - config
    targets:
      # only push it to the us-east-1 provider
      - us-east-1

  # everything with the exception of the us-east-1 .net zones are available
  '*us-west-2':
    regex: '^.*us-west-2.*.net.$'
    sources:
      - config
    targets:
      # only push it to the us-east-1 provider
      - us-west-2

  # legacy style match everything that's left, all our various public zones
  '*':
    sources:
      - config
    targets:
      # push it to the public dns
      - public
      # and private
      - private

Added in version 1.14.0: Regular expression matching support was added in 1.14.0