octodns.processor.filter

Classes

`AllowsMixin`()
`ExcludeRootNsChanges`(name[, error])	Do not allow root NS record changes
`IgnoreRootNsFilter`(name[, lenient])	Do not manage Root NS Records.
`NameAllowlistFilter`(name, allowlist, **kwargs)	Only manage records with names that match the provider patterns
`NameRejectlistFilter`(name, rejectlist, **kwargs)	Reject managing records with names that match the provider patterns
`NetworkValueAllowlistFilter`(name, allowlist, ...)	Only manage A and AAAA records with values that match the provider patterns All other types will be left as-is.
`NetworkValueRejectlistFilter`(name, ...)	Reject managing A and AAAA records with value matching a that match the provider patterns All other types will be left as-is.
`RejectsMixin`()
`TypeAllowlistFilter`(name, allowlist, **kwargs)	Only manage records of the specified type(s).
`TypeRejectlistFilter`(name, rejectlist, **kwargs)	Ignore records of the specified type(s).
`ValueAllowlistFilter`(name, allowlist, **kwargs)	Only manage records with values that match the provider patterns
`ValueRejectlistFilter`(name, rejectlist, **kwargs)	Reject managing records with names that match the provider patterns
`ZoneNameFilter`(name[, error])	Filter or error on record names that contain the zone name

class octodns.processor.filter._FilterProcessor(name, include_target=True, **kwargs)[source]

Bases: BaseProcessor

__init__(name, include_target=True, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

process_source_zone(desired, sources, lenient=False)[source]

Process the desired zone after all sources have populated.

Called after all sources have completed populate. Provides an opportunity for the processor to modify the desired zone that targets will receive.

Parameters:

desired (octodns.zone.Zone) – The desired zone state after all sources have populated. This zone will be used as the target state for planning.
sources (list[octodns.provider.base.BaseProvider]) – List of source providers that populated the zone. May be empty for aliased zones.
lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

The modified desired zone, typically the same object passed in.

Return type:

octodns.zone.Zone

Important

Will see desired after any modifications done by Provider._process_desired_zone and processors configured to run before this one.
May modify desired directly.
Must return desired which will normally be the desired param.
Must not modify records directly; record.copy should be called, the results of which can be modified, and then Zone.add_record may be used with replace=True.
May call Zone.remove_record to remove records from desired.
Sources may be empty, as will be the case for aliased zones.
Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).

process_target_zone(existing, target, lenient=False)[source]

Process the existing zone after the target has populated.

Called after a target has completed populate, before changes are computed between existing and desired. This provides an opportunity to modify the existing zone state.

Parameters:

existing (octodns.zone.Zone) – The current zone state from the target provider.
target (octodns.provider.base.BaseProvider) – The target provider that populated the existing zone.
lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

The modified existing zone, typically the same object passed in.

Return type:

octodns.zone.Zone

Important

Will see existing after any modifications done by processors configured to run before this one.
May modify existing directly.
Must return existing which will normally be the existing param.
Must not modify records directly; record.copy should be called, the results of which can be modified, and then Zone.add_record may be used with replace=True.
May call Zone.remove_record to remove records from existing.
Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).

class octodns.processor.filter.AllowsMixin[source]

Bases: object

matches(zone, record)[source]

doesnt_match(zone, record)[source]

class octodns.processor.filter.RejectsMixin[source]

Bases: object

matches(zone, record)[source]

doesnt_match(zone, record)[source]

class octodns.processor.filter._TypeBaseFilter(name, _list, **kwargs)[source]

Bases: _FilterProcessor

__init__(name, _list, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

_process(zone, sources_or_target, lenient=False)[source]

class octodns.processor.filter.TypeAllowlistFilter(name, allowlist, **kwargs)[source]

Bases: _TypeBaseFilter, AllowsMixin

Only manage records of the specified type(s).

Example usage:

processors:
  only-a-and-aaaa:
    class: octodns.processor.filter.TypeAllowlistFilter
    allowlist:
      - A
      - AAAA
    # Optional param that can be set to False to leave the target zone
    # alone, thus allowing deletion of existing records
    # (default: true)
    # include_target: True

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - only-a-and-aaaa
    targets:
      - ns1

__init__(name, allowlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter.TypeRejectlistFilter(name, rejectlist, **kwargs)[source]

Bases: _TypeBaseFilter, RejectsMixin

Ignore records of the specified type(s).

Example usage:

processors:
  ignore-cnames:
    class: octodns.processor.filter.TypeRejectlistFilter
    rejectlist:
      - CNAME
    # Optional param that can be set to False to leave the target zone
    # alone, thus allowing deletion of existing records
    # (default: true)
    # include_target: True

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - ignore-cnames
    targets:
      - route53

__init__(name, rejectlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter._NameBaseFilter(name, _list, **kwargs)[source]

Bases: _FilterProcessor

__init__(name, _list, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

_process(zone, sources_or_target, lenient=False)[source]

class octodns.processor.filter.NameAllowlistFilter(name, allowlist, **kwargs)[source]

Bases: _NameBaseFilter, AllowsMixin

Only manage records with names that match the provider patterns

Example usage:

processors:
  only-these:
    class: octodns.processor.filter.NameAllowlistFilter
    allowlist:
      # exact string match
      - www
      # contains/substring match
      - /substring/
      # regex pattern match
      - /some-pattern-\d\+/
      # regex - anchored so has to match start to end
      - /^start-.+-end$/
    # Optional param that can be set to False to leave the target zone
    # alone, thus allowing deletion of existing records
    # (default: true)
    # include_target: True

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - only-these
    targets:
      - route53

__init__(name, allowlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter.NameRejectlistFilter(name, rejectlist, **kwargs)[source]

Bases: _NameBaseFilter, RejectsMixin

Reject managing records with names that match the provider patterns

Example usage:

processors:
  not-these:
    class: octodns.processor.filter.NameRejectlistFilter
    rejectlist:
      # exact string match
      - www
      # contains/substring match
      - /substring/
      # regex pattern match
      - /some-pattern-\d\+/
      # regex - anchored so has to match start to end
      - /^start-.+-end$/
    # Optional param that can be set to False to leave the target zone
    # alone, thus allowing deletion of existing records
    # (default: true)
    # include_target: True

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - not-these
    targets:
      - route53

__init__(name, rejectlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter._ValueBaseFilter(name, _list, **kwargs)[source]

Bases: _FilterProcessor

__init__(name, _list, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

_process(zone, sources_or_target, lenient=False)[source]

class octodns.processor.filter.ValueAllowlistFilter(name, allowlist, **kwargs)[source]

Bases: _ValueBaseFilter, AllowsMixin

Only manage records with values that match the provider patterns

Example usage:

processors:
  only-these:
    class: octodns.processor.filter.ValueAllowlistFilter
    allowlist:
      # exact string match
      - www
      # contains/substring match
      - /substring/
      # regex pattern match
      - /some-pattern-\d\+/
      # regex - anchored so has to match start to end
      - /^start-.+-end$/
    # Optional param that can be set to False to leave the target zone
    # alone, thus allowing deletion of existing records
    # (default: true)
    # include_target: True

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - only-these
    targets:
      - route53

__init__(name, allowlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter.ValueRejectlistFilter(name, rejectlist, **kwargs)[source]

Bases: _ValueBaseFilter, RejectsMixin

Reject managing records with names that match the provider patterns

Example usage:

processors:
  not-these:
    class: octodns.processor.filter.ValueRejectlistFilter
    rejectlist:
      # exact string match
      - www
      # contains/substring match
      - /substring/
      # regex pattern match
      - /some-pattern-\d\+/
      # regex - anchored so has to match start to end
      - /^start-.+-end$/
    # Optional param that can be set to False to leave the target zone
    # alone, thus allowing deletion of existing records
    # (default: true)
    # include_target: True

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - not-these
    targets:
      - route53

__init__(name, rejectlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter._NetworkValueBaseFilter(name, _list, **kwargs)[source]

Bases: BaseProcessor

__init__(name, _list, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

_process(zone, *args, **kwargs)[source]

process_source_zone(zone, *args, **kwargs)

Process the desired zone after all sources have populated.

Called after all sources have completed populate. Provides an opportunity for the processor to modify the desired zone that targets will receive.

Parameters:

desired (octodns.zone.Zone) – The desired zone state after all sources have populated. This zone will be used as the target state for planning.
sources (list[octodns.provider.base.BaseProvider]) – List of source providers that populated the zone. May be empty for aliased zones.
lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

The modified desired zone, typically the same object passed in.

Return type:

octodns.zone.Zone

Important

Will see desired after any modifications done by Provider._process_desired_zone and processors configured to run before this one.
May modify desired directly.
Must return desired which will normally be the desired param.
Must not modify records directly; record.copy should be called, the results of which can be modified, and then Zone.add_record may be used with replace=True.
May call Zone.remove_record to remove records from desired.
Sources may be empty, as will be the case for aliased zones.
Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).

process_target_zone(zone, *args, **kwargs)

Process the existing zone after the target has populated.

Called after a target has completed populate, before changes are computed between existing and desired. This provides an opportunity to modify the existing zone state.

Parameters:

existing (octodns.zone.Zone) – The current zone state from the target provider.
target (octodns.provider.base.BaseProvider) – The target provider that populated the existing zone.
lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

The modified existing zone, typically the same object passed in.

Return type:

octodns.zone.Zone

Important

Will see existing after any modifications done by processors configured to run before this one.
May modify existing directly.
Must return existing which will normally be the existing param.
Must not modify records directly; record.copy should be called, the results of which can be modified, and then Zone.add_record may be used with replace=True.
May call Zone.remove_record to remove records from existing.
Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).

class octodns.processor.filter.NetworkValueAllowlistFilter(name, allowlist, **kwargs)[source]

Bases: _NetworkValueBaseFilter, AllowsMixin

Only manage A and AAAA records with values that match the provider patterns All other types will be left as-is.

Example usage:

processors:
  only-these:
    class: octodns.processor.filter.NetworkValueAllowlistFilter
    allowlist:
      - 127.0.0.1/32
      - 192.168.0.0/16
      - fd00::/8

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - only-these
    targets:
      - route53

__init__(name, allowlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter.NetworkValueRejectlistFilter(name, rejectlist, **kwargs)[source]

Bases: _NetworkValueBaseFilter, RejectsMixin

Reject managing A and AAAA records with value matching a that match the provider patterns All other types will be left as-is.

Example usage:

processors:
  not-these:
    class: octodns.processor.filter.NetworkValueRejectlistFilter
    rejectlist:
      - 127.0.0.1/32
      - 192.168.0.0/16
      - fd00::/8

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - not-these
    targets:
      - route53

__init__(name, rejectlist, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

class octodns.processor.filter.IgnoreRootNsFilter(name, lenient=False)[source]

Bases: BaseProcessor

Do not manage Root NS Records.

Example usage:

processors:
  no-root-ns:
    class: octodns.processor.filter.IgnoreRootNsFilter

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - no-root-ns
    targets:
      - ns1

_process(zone, *args, **kwargs)[source]

process_source_zone(zone, *args, **kwargs)

Process the desired zone after all sources have populated.

Called after all sources have completed populate. Provides an opportunity for the processor to modify the desired zone that targets will receive.

Parameters:

desired (octodns.zone.Zone) – The desired zone state after all sources have populated. This zone will be used as the target state for planning.
sources (list[octodns.provider.base.BaseProvider]) – List of source providers that populated the zone. May be empty for aliased zones.
lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

The modified desired zone, typically the same object passed in.

Return type:

octodns.zone.Zone

Important

Will see desired after any modifications done by Provider._process_desired_zone and processors configured to run before this one.
May modify desired directly.
Must return desired which will normally be the desired param.
Must not modify records directly; record.copy should be called, the results of which can be modified, and then Zone.add_record may be used with replace=True.
May call Zone.remove_record to remove records from desired.
Sources may be empty, as will be the case for aliased zones.
Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).

process_target_zone(zone, *args, **kwargs)

Process the existing zone after the target has populated.

Called after a target has completed populate, before changes are computed between existing and desired. This provides an opportunity to modify the existing zone state.

Parameters:

existing (octodns.zone.Zone) – The current zone state from the target provider.
target (octodns.provider.base.BaseProvider) – The target provider that populated the existing zone.
lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

The modified existing zone, typically the same object passed in.

Return type:

octodns.zone.Zone

Important

Will see existing after any modifications done by processors configured to run before this one.
May modify existing directly.
Must return existing which will normally be the existing param.
Must not modify records directly; record.copy should be called, the results of which can be modified, and then Zone.add_record may be used with replace=True.
May call Zone.remove_record to remove records from existing.
Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).

class octodns.processor.filter.ExcludeRootNsChanges(name, error=True, **kwargs)[source]

Bases: BaseProcessor

Do not allow root NS record changes

Example usage:

processors:
  exclude-root-ns-changes:
    class: octodns.processor.filter.ExcludeRootNsChanges
    # If true an a change for a root NS is seen an error will be thrown.
    # If false a warning will be printed and the change will be removed
    # from the plan.
    # (default: true)
    error: true

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - exclude-root-ns-changes
    targets:
      - ns1

__init__(name, error=True, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

process_plan(plan, sources, target, lenient=False)[source]

Process the plan after it has been computed.

Called after the planning phase has completed. Provides an opportunity for the processor to modify the plan, thus changing the actions that will be displayed and potentially applied.

Parameters:

plan (octodns.provider.plan.Plan or None) – The computed plan containing the changes to be applied. May be None if no changes were detected.
sources (list[octodns.provider.base.BaseProvider]) – List of source providers for this zone. May be empty for aliased zones.
target (octodns.provider.base.BaseProvider) – The target provider for which the plan was created.
lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

The modified plan, which may be the same object passed in, a newly created Plan, or None if no changes are needed.

Return type:

octodns.provider.plan.Plan or None

Important

plan may be None if no changes were detected; if so, a Plan may still be created and returned.
May modify plan.changes directly or create a new Plan.
Does not have to modify plan.desired and/or plan.existing to line up with any modifications made to plan.changes.
Should copy over plan.exists, plan.update_pcent_threshold, and plan.delete_pcent_threshold when creating a new Plan.
Must return a Plan which may be plan or can be a newly created one with plan.desired and plan.existing copied over as-is or modified.
Sources may be empty, as will be the case for aliased zones.
Implementations should combine self.lenient or lenient and pass the result to any record and zone calls that accept lenient as a parameter, e.g. zone.add_record(..., lenient=lenient).

class octodns.processor.filter.ZoneNameFilter(name, error=True, **kwargs)[source]

Bases: _FilterProcessor

Filter or error on record names that contain the zone name

Example usage:

processors:
  zone-name:
    class: octodns.processor.filter.ZoneNameFilter
    # If true a ValidationError will be throw when such records are
    # encouterd, if false the records will just be ignored/omitted.
    # (default: true)
    # error: True
    # Optional param that can be set to False to leave the target zone
    # alone, thus allowing deletion of existing records
    # (default: true)
    # include_target: True

zones:
  exxampled.com.:
    sources:
      - config
    processors:
      - zone-name
    targets:
      - azure

__init__(name, error=True, **kwargs)[source]

Initialize the processor.

Parameters:

name (str) – Unique identifier for this processor instance. Used in logging and configuration references.
lenient (bool) – When True, the processor will operate in lenient mode. This value is combined with the per-call lenient parameter in process_* methods.

Note

The name parameter is deprecated and will be removed in version 2.0. Use id instead.

_process(zone, sources_or_target, lenient=False)[source]