Metadata-Version: 2.4
Name: octodns-nested-zones
Version: 0.3.0
Summary: Nested zone source for octoDNS - combine records from a zone and its sub-zones
Project-URL: Homepage, https://gitlab.com/arbu/octodns-nested-zones
Project-URL: Source, https://gitlab.com/arbu/octodns-nested-zones
Project-URL: Issues, https://gitlab.com/arbu/octodns-nested-zones/issues
Author: Aaron Bulmahn
License-Expression: MIT
Keywords: dns,dns-as-code,nested,octodns,sub-zones
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: octodns>=1.5.0
Description-Content-Type: text/markdown

# octodns-nested-zones

Nested zone source for [octoDNS](https://github.com/octodns/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

```bash
pip install octodns-nested-zones
```

## Configuration

Use a YAML anchor to share the inner source configuration:

```yaml
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

```bash
# 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](CHANGELOG.md) for release history.

## License

MIT
