OpsDev.nz Utilities

Reference material generated from the op_opsdevnz package. These helpers power the OctoDNS Metaname provider integration and other internal automation.

1Password helper

1Password helpers for OpsDev.nz.

Provides a thin wrapper around the official Service Account SDK with an optional fallback to the op CLI so local developers can resolve op:// references without additional tooling.

SecretError

Bases: RuntimeError

Raised when secret resolution fails.

Source code in opsdevnz/onepassword.py

class SecretError(RuntimeError):
    """Raised when secret resolution fails."""

SecretResolution dataclass

Result of resolving a secret, including which resolver was used.

Source code in opsdevnz/onepassword.py

@dataclass
class SecretResolution:
    """Result of resolving a secret, including which resolver was used."""

    value: str
    source: SecretSource

resolve_secret(*, secret_ref_env=None, secret_ref=None, env_override=None, prefer_cli=False, timeout=10.0)

Resolve a 1Password secret and report which resolver produced it.

Resolution order

1. Return env_override when set (local overrides, CI tests).
2. Resolve the provided secret_ref or the value from secret_ref_env (must point to an op:// reference).
3. Use the Service Account SDK by default, falling back to the CLI when prefer_cli is true or the SDK path fails and the CLI is available.

Source code in opsdevnz/onepassword.py

def resolve_secret(
    *,
    secret_ref_env: Optional[str] = None,
    secret_ref: Optional[str] = None,
    env_override: Optional[str] = None,
    prefer_cli: bool = False,
    timeout: float = 10.0,
) -> SecretResolution:
    """Resolve a 1Password secret and report which resolver produced it.

    Resolution order:
        1. Return ``env_override`` when set (local overrides, CI tests).
        2. Resolve the provided ``secret_ref`` or the value from
           ``secret_ref_env`` (must point to an ``op://`` reference).
        3. Use the Service Account SDK by default, falling back to the CLI when
           ``prefer_cli`` is true or the SDK path fails and the CLI is available.
    """

    if env_override and (value := os.getenv(env_override)):
        return SecretResolution(value=value, source="env")

    reference = secret_ref or (os.getenv(secret_ref_env) if secret_ref_env else None)
    if not reference or not reference.startswith("op://"):
        raise SecretError("A valid 1Password secret reference is required (op://Vault/Item/Field)")

    if prefer_cli:
        try:
            value = _resolve_via_cli(reference, timeout=timeout)
            return SecretResolution(value=value, source="cli")
        except SecretError as cli_error:
            # fall back to SDK when available so CI/service-account flows still work
            try:
                value = _resolve_via_sdk(reference)
                return SecretResolution(value=value, source="sdk")
            except SecretError:
                # raise original CLI error to preserve context for local devs
                raise cli_error from None

    try:
        value = _resolve_via_sdk(reference)
        return SecretResolution(value=value, source="sdk")
    except SecretError:
        if shutil.which("op"):
            value = _resolve_via_cli(reference, timeout=timeout)
            return SecretResolution(value=value, source="cli")
        raise

get_secret(*, secret_ref_env=None, secret_ref=None, env_override=None, prefer_cli=False, timeout=10.0)

Backward-compatible helper that returns only the secret value.

Source code in opsdevnz/onepassword.py

def get_secret(
    *,
    secret_ref_env: Optional[str] = None,
    secret_ref: Optional[str] = None,
    env_override: Optional[str] = None,
    prefer_cli: bool = False,
    timeout: float = 10.0,
) -> str:
    """Backward-compatible helper that returns only the secret value."""

    return resolve_secret(
        secret_ref_env=secret_ref_env,
        secret_ref=secret_ref,
        env_override=env_override,
        prefer_cli=prefer_cli,
        timeout=timeout,
    ).value

1Password SDK utilities

Async helpers for resolving 1Password secrets via the official SDK.

get_secret_from_ref_env(ref_env, *, env_override=None)

Synchronously resolve a secret reference stored in an env var.

Source code in opsdevnz/onepassword_sdk.py

def get_secret_from_ref_env(ref_env: str, *, env_override: Optional[str] = None) -> str:
    """Synchronously resolve a secret reference stored in an env var."""

    if env_override and (value := os.getenv(env_override)):
        return value
    reference = os.getenv(ref_env)
    if not reference:
        raise SecretError(f"{ref_env} is not set")
    if not reference.startswith("op://"):
        raise SecretError(f"{ref_env} must contain an op:// reference")
    return asyncio.run(_resolve_ref_async(reference))

OctoDNS hooks

Integration helpers between OctoDNS Metaname provider and opsdevnz secrets.

resolve(name, reference=None)

Resolve secrets via 1Password using the opsdevnz helper.

Parameters

name: Logical name of the secret (e.g., METANAME_API_TOKEN). reference: Optional reference retrieved from <NAME>_REF. When present this is passed directly to 1Password; otherwise we rely on opsdevnz_get_secret to look up any matching reference env variable.

Source code in opsdevnz/octodns_hooks.py

def resolve(name: str, reference: Optional[str] = None) -> Optional[str]:
    """Resolve secrets via 1Password using the opsdevnz helper.

    Parameters
    ----------
    name:
        Logical name of the secret (e.g., ``METANAME_API_TOKEN``).
    reference:
        Optional reference retrieved from ``<NAME>_REF``. When present this is
        passed directly to 1Password; otherwise we rely on ``opsdevnz_get_secret``
        to look up any matching reference env variable.
    """

    if reference:
        return opsdevnz_get_secret(
            secret_ref=reference,
            env_override=name,
            prefer_cli=True,
        )
    return opsdevnz_get_secret(
        secret_ref_env=f"{name}_REF",
        env_override=name,
        prefer_cli=True,
    )