Skip to content

DNS Change Workflow

This guide describes how to make and validate DNS changes in the OpsDev.nz repository using the OctoDNS Metaname provider.

Prerequisites

  • Python 3.13+ with the requirements-dev.txt dependencies installed (includes OctoDNS and the op_opsdevnz helpers).
  • Access to the Metaname sandbox or production credentials via 1Password.
  • A configured environment file such as env/metaname-test-opstest.env that defines the *_REF secret references used by the provider.

1. Update zone data

  1. Edit the relevant file under zones/ (for example zones/opstest.nz.yaml) to add, modify or remove records.
  2. If the change requires configuration updates (new providers, processors, transforms), adjust the corresponding file under configs/.

2. Prepare environment variables

export OCTODNS_METANAME_SECRET_RESOLVER="op_opsdevnz.octodns_hooks:resolve"
source env/metaname-test-opstest.env

The resolver bridges OctoDNS to the shared 1Password helper so references like METANAME_API_TOKEN_REF can be resolved automatically. Environment files under env/ already export their variables so set -a shells are no longer required.

3. Validate locally

Run the standard validation sequence from the repository root:

octodns-validate --config-file configs/config.opstest.yaml
octodns-sync --config-file configs/config.opstest.yaml

Without --doit, octodns-sync performs a dry-run and prints the proposed DNS changes. Review the output for any unexpected diffs before committing; re-run with --doit only when you are ready to push updates to Metaname.

4. Commit and push

Create a new branch, commit the zone/config changes, and push to GitLab. The CI pipeline runs when files matching the following patterns change:

  • configs/**
  • modules/octodns_metaname/**
  • scripts/**
  • zones/**
  • env/metaname-*.env

plan_test and plan_prod jobs publish artefacts (octodns-plan-*.txt) that mirror the local dry-run output. Download them from the pipeline page to verify the remote plan if needed.

5. Apply changes

Deployment jobs (apply_test and apply_prod) are manual and should be run in GitLab once the plan output looks correct. Launching these jobs requires the appropriate 1Password service-account variables to be configured in the project’s CI settings.

6. Update documentation

If the workflow introduced new processes, update the MkDocs pages under website/docs/ so the wider team can follow the same steps. Regenerate the site locally with mkdocs build or mkdocs serve and include the Markdown updates with your merge request.