octodns.processor.base

Classes

BaseProcessor(name[, lenient])

Base class for all octoDNS processors.

Exceptions

ProcessorException

Exception raised when a processor encounters an error during processing.
exception octodns.processor.base.ProcessorException[source]

Bases: Exception

Exception raised when a processor encounters an error during processing.

A subclass of this exception can be raised by processors when they encounter invalid configurations, unsupported operations, or other processing errors.

class octodns.processor.base.BaseProcessor(name, lenient=False)[source]

Bases: object

Base class for all octoDNS processors.

Processors provide hooks into the octoDNS sync process to modify zones and records at various stages. They can be used to filter, transform, or validate DNS records before planning and applying changes.

Processors are executed in the order they are configured and can modify:

  • Source zones (after sources populate, before planning)

  • Target zones (after target populates, before planning)

  • Source and target zones (just before computing changes)

  • Plans (after planning, before applying)

Subclasses should override one or more of the process_* methods to implement custom processing logic.

Example usage:

processors:
  my-processor:
    class: my.custom.processor.MyProcessor
    # processor-specific configuration

zones:
  example.com.:
    sources:
      - config
    processors:
      - my-processor
    targets:
      - route53

See also

__init__(name, lenient=False)[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).

process_source_and_target_zones(desired, existing, target, lenient=False)[source]

Process both desired and existing zones before computing changes.

Called just prior to computing changes for the target provider between desired and existing. Provides an opportunity for the processor to modify either or both zones that will be used to compute the changes and create the initial plan.

Parameters:

  • desired (octodns.zone.Zone) – The desired zone state after all source processing.

  • existing (octodns.zone.Zone) – The existing zone state after all target processing.

  • target (octodns.provider.base.BaseProvider) – The target provider for which changes will be computed.

  • lenient (bool) – When True, relaxed validation rules should be applied when modifying zone records.

Returns:

A tuple of (desired, existing) zones, typically the same objects passed in.

Return type:

tuple[octodns.zone.Zone, octodns.zone.Zone]

Important

  • Will see desired after any modifications done by Provider._process_desired_zone and all processors via Processor.process_source_zone.

  • Will see existing after any modifications done by all processors via Processor.process_target_zone.

  • Will see both desired and existing after any modifications done by any processors configured to run before this one via Processor.process_source_and_target_zones.

  • May modify desired directly.

  • Must return desired which will normally be the desired param.

  • 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 desired.

  • 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).

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:
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).