Zone Lifecycle During Sync

This document describes the lifecycle of a Zone object during the sync process in octoDNS. The octodns.manager.Manager.sync() method is the entry point for this process.

Zone Creation and Population

  • Zone object creation: Zone objects are created by octodns.manager.Manager.get_zone() with the zone name, configured sub-zones, and threshold values from the configuration

  • Source population: The populate() method is called for each source to add records to the zone

    • Sources iterate through their data and call add_record() to add each record

  • Source zone processing:

    • process_source_zone() is then called for each configured processor allowing them to modify or filter the populated zone

Planning Phase

  • Plan creation: Each target provider’s plan() method is called with the final the desired (source) zone

  • Existing zone population: A new empty Zone is created to represent the target’s current state

    • The target provider populates this zone via populate() with target=True and lenient=True

    • This additonally return whether the zone exists in the target

  • Desired zone copy: A shallow copy of the desired zone is created via copy()

    • Uses copy-on-write semantics for efficiency

    • Actual record copying is deferred until modifications are needed

  • Desired zone processing: The target provider calls _process_desired_zone() to adapt records for the target

    • Removes unsupported record types

    • Handles dynamic record support/fallback

    • Handles multi-value PTR record support

    • Handles root NS record support

    • May warn or raise exceptions based on strict_supports setting

    • Providers may overide this method to add additional checks or modifications, they must always call super to allow the above processing

  • Existing zone processing: The target provider calls _process_existing_zone() to normalize existing records

    • Filters out existing root NS records if not supported or not in desired

  • Target zone processing: Each processor’s process_target_zone() is called to modify the existing (target) zone for this provider

    • Processors can filter or modify what octoDNS sees as the current state

  • Source and target zone processing: Each processor calls process_source_and_target_zones() with both zones

    • Allows processors to make coordinated changes to both desired and existing states

  • Change detection: The existing zone’s changes() method compares existing records to desired records

    • Identifies records to create, update, or delete

    • Honors record-level ignored, included, and excluded flags

    • Skips records not supported by the target

  • Change filtering: The target provider’s _include_change() method filters false positive changes

    • Providers can exclude changes due to implementation details (e.g., minimum TTL enforcement)

  • Extra changes: The target provider’s _extra_changes() method adds provider-specific changes

    • Allows providers to add changes for ancillary records or zone configuration

  • Meta changes: The target provider’s _plan_meta() method provides additional non-record change information

    • Used for zone-level settings or metadata

  • Plan processing: Each processor calls process_plan() to modify or filter the plan

    • Processors can add, modify, or remove changes from the plan

  • Plan finalization: A Plan object is created if changes exist

    • Contains the existing zone, desired zone, list of changes, and metadata

    • Returns None if no changes are needed

Plan Output and Safety Checks

  • Plan output: All configured plan outputs run to display or record the plan

  • Safety validation: Each plan’s raise_if_unsafe() method checks for dangerous/numerous changes (unless force=True)

    • Validates update and delete percentages against thresholds

    • Requires force for root NS record changes

    • Raises UnsafePlan if thresholds exceeded

Apply Phase

  • Change application: Each target provider’s apply() method is called if not in dry-run mode

    • Calls the provider’s _apply() method to submit changes

    • The _apply implementation is provider-specific and interacts with the DNS provider’s API

    • Returns the number of changes applied

  • Completion: The sync process completes and returns the total number of changes made across all zones and targets