octodns-nested-zones

Nested zone source for octoDNS.

Combines records from a source zone and its configured sub-zones into a single zone. This is useful when an upstream provider (e.g. AXFR) is limited to a single zone at a time but you need to sync records from multiple zones into a target that does not support zones on subdomains.

Motivation

Providers like AXFR (zone transfer) are scoped to one zone. If you have delegated sub-domains managed in separate zones (e.g. sub1.example.com, sub2.example.com), a plain AXFR source for example.com will only see records from the example.com zone itself - it would not include the records that live in the sub-zone files.

This source wraps another source (like AXFR) and:

1. Fetches records for the primary zone
2. Fetches records for each configured sub-zone
3. Merges everything into a single combined zone

The merged zone can then be synced to any target provider that doesn't understand or cares about zone boundaries.

Installation

pip install octodns-nested-zones

Configuration

Use a YAML anchor to share the inner source configuration:

providers:
  axfr: &axfr
    class: octodns.source.axfr.AxfrSource
    host: ns1.example.com
    key: env/AXFR_KEY

  nested:
    class: octodns_nested_zones.NestedSource
    source: *axfr
    sub_zones:
      - sub1
      - sub2

zones:
  example.com.:
    sources:
      - nested
    targets:
      - your_dns_provider

Each entry in sub_zones is relative to the primary zone - e.g. sub1 resolves to sub1.example.com. when populating the example.com. zone.

How it works

On each sync cycle, the source:

1. Calls the inner source's populate() for the primary zone
2. For each sub-zone, creates a temporary Zone, calls the inner source's populate(), then copies the records into the primary zone with their full qualified names (e.g. a record app from the sub1.example.com. zone becomes app.sub1 in example.com.)
3. All records (primary and sub-zone) end up in the same zone

Development

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest

Releasing

1. Update CHANGELOG.md — move the new version's entry from - unreleased to a date and add any missing items.
2. Commit and push to main.
3. Tag the release: git tag 0.2.0 && git push --tags.

CI will run the test suite, build the package, create a GitLab Release with the changelog section, and publish to PyPI.

Changes

See CHANGELOG.md for release history.

License

MIT