octodns-metaname

OctoDNS provider for the Metaname DNS API, originally bootstrapped from the upstream octodns-template. Use it to run a DNS-as-Code workflow with OctoDNS for any zones you host at Metaname.

Installation

PyPI release:

pip install octodns-metaname

If you rely on the OpsDev.nz 1Password resolver, install the optional extra:

pip install octodns-metaname[onepassword]

Editable install for local development:

python -m venv venv && source venv/bin/activate
pip install -e .[dev]

OctoDNS integration

Once installed, the provider is available via the entry point metaname. Sample config.yaml fragment:

providers:
  metaname-test:
    class: octodns_metaname.MetanameProvider
    base_url: https://test.metaname.net/api/1.1

Populate/apply workflows follow the standard OctoDNS CLI tools. Consult the OctoDNS docs for full CLI details.

Domain lifecycle CLI

Domain registration is separate from DNS record management. The CLI defaults to Metaname's test API:

octodns-metaname check example.nz
octodns-metaname list
octodns-metaname register example.nz --term 12 --confirm

Pass --production before the command to use the live API. Registration requires --confirm because it consumes test credit or incurs a production charge. Omitting --nameserver selects Metaname hosted DNS.

Optional registration during apply

The provider can register a missing domain immediately before applying its records. This is disabled by default and should normally be enabled only for the test API:

providers:
  metaname-test:
    class: octodns_metaname.MetanameProvider
    base_url: https://test.metaname.net/api/1.1
    auto_register_domains: true
    registration_term: 12

The dry-run only reports the proposed records. Registration happens during the subsequent octodns-sync --doit apply. For the production API, an additional allow_production_registration: true safeguard is required. Prefer the CLI for an explicit availability check and registration before enabling production automation.

Secret resolution

By default the provider reads secrets directly from environment variables such as METANAME_ACCOUNT_REF and METANAME_API_TOKEN. If your workflow stores values in a vault (e.g., 1Password) you can register a resolver using:

from octodns_metaname import secrets

def resolve(name: str, reference: str | None) -> str | None:
    ...

secrets.set_secret_resolver(resolve)

For CLI usage set OCTODNS_METANAME_SECRET_RESOLVER="module:function" so the resolver is loaded automatically. OpsDev.nz deployments point this at octodns_metaname.op_opsdevnz_hooks:resolve, provided by the optional onepassword extra. The adapter uses op-opsdevnz for the underlying Service Account SDK/CLI resolution.

Install the integration with:

pip install "octodns-metaname[onepassword]"

Development

# Create/update the project environment from uv.lock
uv sync --extra dev --extra onepassword

# Run tools inside the project environment
uv run ruff check src tests
uv run mypy src
uv run pytest --maxfail=1

# Build the documentation site
uv run zensical build

The onepassword extra installs the optional op-opsdevnz integration used by the Metaname secret resolver. uv run ensures commands use the project environment rather than a user-level Python installation.

The repo includes a GitHub Actions workflow that runs linting, type checking, tests, and a build on every push.

Releasing

See RELEASING.md for the full TestPyPI → PyPI checklist.

License

Apache-2.0 © OpsDev.nz