Skip to content

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 
21
22
class SecretError(RuntimeError):
    """Raised when secret resolution fails."""

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

Resolve a 1Password secret.

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 
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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:
    """Resolve a 1Password secret.

    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 value

    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:
        cli_error: Optional[SecretError] = None
        try:
            return _resolve_via_cli(reference, timeout=timeout)
        except SecretError as exc:
            cli_error = exc
            # fall back to SDK when available so CI/service-account flows still work
            try:
                return _resolve_via_sdk(reference)
            except SecretError:
                # raise original CLI error to preserve context for local devs
                raise cli_error

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

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 
33
34
35
36
37
38
39
40
41
42
43
def get_secret_from_ref_env(ref_env: str, *, env_override: str | None = 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 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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,
    )