Metadata-Version: 2.4
Name: octodns-metaname
Version: 0.3.0
Summary: OpsDev.nz OctoDNS provider for the Metaname DNS API
Author-email: "OpsDev.nz Platform Engineering" <john@opsdev.nz>
Maintainer-email: "OpsDev.nz Platform Engineering" <john@opsdev.nz>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/startmeup-nz/octodns-metaname
Project-URL: Source, https://github.com/startmeup-nz/octodns-metaname
Project-URL: Issues, https://github.com/startmeup-nz/octodns-metaname/issues
Keywords: octodns,metaname,dns,opsdevnz
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: Name Service (DNS)
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: octodns<2.0,>=1.22
Requires-Dist: requests>=2.34.2
Provides-Extra: dev
Requires-Dist: build>=1.5.0; extra == "dev"
Requires-Dist: mypy>=2.3.1; extra == "dev"
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: ruff>=0.16.3; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Requires-Dist: vcrpy>=8.0.0; extra == "dev"
Requires-Dist: types-requests>=2.33.0.20260712; extra == "dev"
Requires-Dist: zensical>=0.0.54; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=9.1.1; extra == "test"
Requires-Dist: pytest-cov>=7.1.0; extra == "test"
Requires-Dist: vcrpy>=8.0.0; extra == "test"
Provides-Extra: onepassword
Requires-Dist: op-opsdevnz>=0.2.1; extra == "onepassword"
Dynamic: license-file

# octodns-metaname

OctoDNS provider for the [Metaname](https://metaname.net) DNS API, originally
bootstrapped from the upstream [`octodns-template`](https://github.com/octodns/octodns-template).
Use it to run a DNS-as-Code workflow with OctoDNS for any zones you host at
Metaname.

## Installation

PyPI release:

```bash
pip install octodns-metaname
```

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

```bash
pip install octodns-metaname[onepassword]
```

Editable install for local development:

```bash
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:

```yaml
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](https://github.com/octodns/octodns/wiki/Usage) for full CLI
details.

### Domain lifecycle CLI

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

```bash
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:

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

```python
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:

```bash
pip install "octodns-metaname[onepassword]"
```

## Development

```bash
# 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](RELEASING.md) for the full TestPyPI → PyPI checklist.

## License

Apache-2.0 © OpsDev.nz
