octodns.provider.yaml

Example Configuration

Core provider for records configured in yaml files on disk:

config:
  class: octodns.provider.yaml.YamlProvider

  # The location of yaml config files. By default records are defined in a
  # file named for the zone in this directory, the zone file, e.g.
  # something.com.yaml.
  # (required)
  directory: ./config

  # The ttl to use for records when not specified in the data
  # (optional, default 3600)
  default_ttl: 3600

  # Whether or not to enforce sorting order when loading yaml
  # (optional, default True)
  enforce_order: true
  # What sort mode to employ when enforcing order
  # - simple: `sort`
  # - natural: https://pypi.org/project/natsort/
  # (optional, default natural)
  order_mode: natural

  # Whether duplicate records should replace rather than error
  # (optional, default False)
  populate_should_replace: false

  # The file extension used when loading split style zones, Null means
  # disabled. When enabled the provider will search for zone records split
  # across multiple YAML files in the directory with split_extension
  # appended to the zone name, See "Split Details" below.
  # split_extension should include the "."
  # (optional, default null, "." is the recommended best practice when
  # enabling)
  split_extension: null

  # When writing YAML records out to disk with split_extension enabled
  # each record is written out into its own file with .yaml appended to
  # the name of the record. The two exceptions are for the root and
  # wildcard nodes. These records are written into a file named
  # `$[zone.name].yaml`. If you would prefer this catchall file not be
  # used `split_catchall` can be set to False to instead write those
  # records out to `.yaml` and `*.yaml` respectively. Note that some
  # operating systems may not allow files with those names.
  # (optional, default True)
  split_catchall: true

  # Optional filename with record data to be included in all zones
  # populated by this provider. Has no effect when used as a target.
  # (optional, default null)
  shared_filename: null

  # Disable loading of the zone .yaml files.
  # (optional, default False)
  disable_zonefile: false

  # Whether or not ; in values, e.g. TXT, need to be escaped \;
  # (optional, default True)
  escaped_semicolons: True

  # Whether to ignore missing zone files when used as a source
  # (optional, default False)
  ignore_missing_zones: False

Note

When using this provider as a target any existing comments or formatting in the zone files will be lost when changes are applyed.

Split Details

All files are stored in a subdirectory matching the name of the zone (including the trailing .) of the directory config. It is a recommended best practice that the files be named RECORD.yaml, but all files are sourced and processed ignoring the filenames so it is up to you how to organize them.

With split_extension: . the directory structure for the zone github.com. managed under directory “zones/” would look like:

zones/
  github.com./
    $github.com.yaml
    www.yaml
    ...

Overriding Values

Overriding values can be accomplished using multiple yaml providers in the sources list where subsequent providers have populate_should_replace set to true. An example use of this would be a zone that you want to push to external DNS providers and internally, but you want to modify some of the records in the internal version.

config/octodns.com.yaml:

---
other:
  type: A
  values:
    - 192.30.252.115
    - 192.30.252.116
www:
  type: A
  values:
    - 192.30.252.113
    - 192.30.252.114

internal/octodns.com.yaml:

---
'www':
  type: A
  values:
    - 10.0.0.12
    - 10.0.0.13

external.yaml:

---
providers:
  config:
    class: octodns.provider.yaml.YamlProvider
    directory: ./config

zones:

  octodns.com.:
    sources:
      - config
    targets:
      - route53

internal.yaml:

---
providers:
  config:
    class: octodns.provider.yaml.YamlProvider
    directory: ./config

  internal:
    class: octodns.provider.yaml.YamlProvider
    directory: ./internal
    populate_should_replace: true

zones:

  octodns.com.:
    sources:
      - config
      - internal
    targets:
      - pdns

You can then sync our records eternally with –config-file=external.yaml and internally (with the custom overrides) with –config-file=internal.yaml

Classes

SplitYamlProvider(id, directory, *args[, ...])

DEPRECATED: Use YamlProvider with the split_extension parameter instead.

YamlProvider(id, directory[, default_ttl, ...])

class octodns.provider.yaml.YamlProvider(id, directory, default_ttl=3600, enforce_order=True, order_mode='natural', populate_should_replace=False, supports_root_ns=True, split_extension=False, split_catchall=True, shared_filename=False, disable_zonefile=False, escaped_semicolons=True, ignore_missing_zones=False, *args, **kwargs)[source]

Bases: BaseProvider

SUPPORTS_GEO = True
SUPPORTS_DYNAMIC = True
SUPPORTS_POOL_VALUE_STATUS = True
SUPPORTS_DYNAMIC_SUBNETS = True
SUPPORTS_MULTIVALUE_PTR = True
CATCHALL_RECORD_NAMES = ('*', '')
__init__(id, directory, default_ttl=3600, enforce_order=True, order_mode='natural', populate_should_replace=False, supports_root_ns=True, split_extension=False, split_catchall=True, shared_filename=False, disable_zonefile=False, escaped_semicolons=True, ignore_missing_zones=False, *args, **kwargs)[source]

Initialize the provider.

Parameters:

  • id (str) – Unique identifier for this provider instance.

  • apply_disabled (bool) – If True, the provider will plan changes but not apply them. Useful for read-only/validation mode.

  • update_pcent_threshold (float) – Maximum percentage of existing records that can be updated in one sync before requiring --force. Default: 0.3 (30%).

  • delete_pcent_threshold (float) – Maximum percentage of existing records that can be deleted in one sync before requiring --force. Default: 0.3 (30%).

  • strict_supports (bool) – If True, raise exceptions when unsupported features are encountered. If False, log warnings and attempt to work around limitations.

  • root_ns_warnings (bool) – If True, log warnings about root NS record handling. If False, silently handle root NS.

copy()[source]
property SUPPORTS
supports(record)[source]

Check if this source supports the given record type.

Parameters:

record (octodns.record.base.Record) – The DNS record to check for support.

Returns:

True if the record type is supported, False otherwise.

Return type:

bool

property SUPPORTS_ROOT_NS

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

list_zones()[source]
_split_sources(zone)[source]
_zone_sources(zone)[source]
_populate_from_file(filename, zone, lenient)[source]
populate(zone, target=False, lenient=False)[source]

Load DNS records from the source into the provided zone.

This method is responsible for reading DNS data from the source’s backend and adding records to the zone using zone.add_record(). Subclasses must implement this method.

Parameters:

  • zone (octodns.zone.Zone) – The zone to populate with records from this source.

  • target (bool) – If True, the populate call is loading the current state from a target provider (for comparison during sync). If False, loading desired state from a source.

  • lenient (bool) – If True, skip strict record validation and do a “best effort” load of data. This allows some non-best-practice configurations through (e.g., missing trailing dots or unescaped semicolons).

Returns:

When target is True (loading current state), should return True if the zone exists in the target or False if it does not. When target is False (loading desired state), return value is ignored and may be None.

Return type:

bool or None

Raises:

NotImplementedError – This base class method must be overridden by subclasses.

Important

  • Must use zone.add_record() to add records to the zone.

  • Should not modify the zone name or other zone properties.

  • When target=True, must return a boolean indicating zone existence.

  • When lenient=True, should relax validation to handle common non-standard configurations.

_apply(plan)[source]

Actually submit the changes to the provider’s backend.

This is an abstract method that must be implemented by all provider subclasses. It should take the changes in the plan and apply them to the provider’s API or backend system.

Parameters:

plan (octodns.provider.plan.Plan) – The plan containing changes to apply.

Raises:

NotImplementedError – This base class method must be overridden by subclasses.

Important

  • Must implement the actual logic to submit changes to the provider.

  • Should handle errors appropriately (log, raise exceptions, etc.).

  • May apply changes in any order that makes sense for the provider with as much safety as possible given the API methods available. Often the order of changes should apply deletes before adds to avoid comflicts during type changes, specidically CNAME <-> other types. If the provider’s API supports batching or atomic changes they should be used.

  • Should be idempotent where possible.

class octodns.provider.yaml.SplitYamlProvider(id, directory, *args, extension='.', **kwargs)[source]

Bases: YamlProvider

DEPRECATED: Use YamlProvider with the split_extension parameter instead.

When migrating the following configuration options would result in the same behavior as SplitYamlProvider:

config:
  class: octodns.provider.yaml.YamlProvider
  # extension is configured as split_extension
  split_extension: .
  split_catchall: true
  disable_zonefile: true

TO BE REMOVED: 2.0

__init__(id, directory, *args, extension='.', **kwargs)[source]

Initialize the provider.

Parameters:

  • id (str) – Unique identifier for this provider instance.

  • apply_disabled (bool) – If True, the provider will plan changes but not apply them. Useful for read-only/validation mode.

  • update_pcent_threshold (float) – Maximum percentage of existing records that can be updated in one sync before requiring --force. Default: 0.3 (30%).

  • delete_pcent_threshold (float) – Maximum percentage of existing records that can be deleted in one sync before requiring --force. Default: 0.3 (30%).

  • strict_supports (bool) – If True, raise exceptions when unsupported features are encountered. If False, log warnings and attempt to work around limitations.

  • root_ns_warnings (bool) – If True, log warnings about root NS record handling. If False, silently handle root NS.