Skip to content

Secret Resolution Flow

The octodns-metaname module can optionally resolve secrets (API tokens, credentials) using the op-opsdevnz helper module.

  1. Secret-resolution adapter (octodns_metaname.op_opsdevnz_hooks) — reads *_REF env vars, decides whether to call 1Password or fall back to plain env values. Worth noting that this does not use the OctoDNS secrets API, because OctoDNS only ships a plain env-var backend (EnvironSecrets) with no 1Password support. We added an extra hook of our own to octodns-metaname for fetching secrets from 1Password because it's the password manager we happen to be using.
  2. Generic 1Password helper (op_opsdevnz.onepassword) — handles the actual op CLI / SDK authentication, shared across all OpsDev.nz tools.

A "ref" is an op://vault/item/field string — 1Password's reference format for pointing to a secret.

flowchart TD
    subgraph OctoDNS["octodns_metaname"]
        A[get_secret] --> B{_secret_resolver?}
    end

    B -- not set --> ENV[Env var<br/>plain value]
    ENV --> DONE

    B -- configured --> C[op_opsdevnz_hooks.resolve]
    C --> D{METANAME_API_TOKEN<br/>plain env var set?}
    D -- yes --> DONE
    D -- no --> E[Read _REF env var<br/>e.g. METANAME_API_TOKEN_REF]
    E --> F{Starts with op://?}
    F -- yes --> G[resolve_secret]
    F -- no --> DONE

    subgraph OP1Password["op_opsdevnz + 1Password"]
        G --> H{OP_SERVICE_ACCOUNT_TOKEN?}
        H -- yes --> I[SDK: service account]
        H -- no --> J[CLI: signed-in session]
    end

    I --> DONE[Secret value]
    J --> DONE

Local development

  • Developers export Metaname refs (*_REF) from an env file, e.g. env/metaname-test.env. Each ref is an op:// string pointing to a 1Password secret.
  • When OctoDNS needs a secret, the secret-resolution adapter reads the *_REF env var and passes it to op_opsdevnz for resolution.
  • op_opsdevnz prefers the local op CLI when no service-account token is present — this supports personal vault access without requiring service-account credentials on a workstation.
  • When OP_SERVICE_ACCOUNT_TOKEN is present, the generic resolver uses the Service Account SDK first and does not silently switch principals after an authentication failure.
  • Direct environment overrides (e.g. METANAME_API_TOKEN=...) short-circuit the resolver, which is handy for testing without touching 1Password.

CI/CD pipeline

  • DNS jobs run in the standard python:3.14-slim image.
  • Pipelines set OCTODNS_METANAME_SECRET_RESOLVER="octodns_metaname.op_opsdevnz_hooks:resolve" before invoking OctoDNS commands.
  • They inject *_REF variables (e.g. METANAME_API_TOKEN_REF) alongside OP_SERVICE_ACCOUNT_TOKEN as CI/CD variables.
  • The secret-resolution adapter uses the generic resolver's service-account path when the token is present. Local workstations without a token prefer the signed-in CLI.
  • Any failure to resolve a secret raises octodns_metaname.secrets.MissingSecret so the job fails fast instead of deploying with missing credentials.