Skip to content

NetBox DB Migration to PostgreSQL HA (HyOps)

Purpose

Migrate existing NetBox records from the bootstrap PostgreSQL database (pgcore) to a PostgreSQL HA cluster before running onprem/netbox-ha-cutover@v1.

This workflow is intentionally separate from cutover:

  • platform/onprem/netbox-db-migrate = data migration (dump/restore)
  • onprem/netbox-ha-cutover@v1 = DB endpoint switch/repoint

Why this matters

hyops inventory sync-netbox can repopulate infrastructure datasets (prefixes, VMs) after cutover, but it does not restore all NetBox data (users, permissions, custom modeling, historical records, plugin data, manually curated objects).

If you want existing NetBox data preserved, run this migration first.

Prerequisites

  • NetBox service is healthy on the source DB (pgcore)
  • Target PostgreSQL HA is deployed and healthy
  • Target HA allows the NetBox host data IP in pg_hba (allowed_clients)
  • Runtime vault decrypt works (for NETBOX_DB_PASSWORD)
  • Maintenance window approved (the migration quiesces NetBox writes)

Module

  • Module ref: platform/onprem/netbox-db-migrate
  • Example inputs: hybridops-core/modules/platform/onprem/netbox-db-migrate/examples/inputs.min.yml

Defaults (state-driven):

  • source DB contract: platform/onprem/postgresql-core
  • target DB contract: platform/onprem/postgresql-ha
  • target host: platform/onprem/platform-vm#platform_vms / netbox-01

Safe sequence (shared NetBox authority)

  1. Preflight (strict)
hyops preflight --env shared --strict \
  --module platform/onprem/netbox-db-migrate \
  --inputs modules/platform/onprem/netbox-db-migrate/examples/inputs.min.yml
  1. Run migration (explicit confirmations required)
HYOPS_INPUT_maintenance_confirm=true \
HYOPS_INPUT_migration_confirm=true \
hyops apply --env shared \
  --module platform/onprem/netbox-db-migrate \
  --inputs modules/platform/onprem/netbox-db-migrate/examples/inputs.min.yml
  1. Run NetBox cutover (switch-only)
hyops blueprint deploy --env shared \
  --ref onprem/netbox-ha-cutover@v1 \
  --execute
  1. Verify NetBox after cutover
curl -sS -D - http://10.10.0.11:8000/ -o /dev/null | head

Safety gates and behavior

  • maintenance_confirm=true and migration_confirm=true are both required
  • By default the module fails if the target DB is not empty
  • To intentionally replace target contents, set:
  • target_replace_confirm=true
  • The module quiesces NetBox services on the NetBox host before dumping/restoring
  • By default it does not restart NetBox after migration (start_netbox_after_migration=false)
  • Cutover should perform the next controlled restart/reconcile

Evidence and outputs

Look in the module evidence directory for:

  • ansible.log
  • driver_result.json
  • module_state.json

Published module state includes:

  • cap.db.netbox_migration = ready
  • migration.dump_path
  • migration.dump_sha256
  • source/target endpoint details
  • validation row counts (core NetBox tables)

Troubleshooting

  • Target database ... already contains tables
  • Either use a fresh HA DB target, or rerun with target_replace_confirm=true during an approved maintenance window.
  • no pg_hba.conf entry ...
  • Add the NetBox host data IP to shared PGHA allowed_clients, then run PGHA maintenance reconcile before retrying migration/cutover.
  • NetBox readiness failed during later cutover
  • Check target PGHA connectivity and pg_hba allowlist, then rerun onprem/netbox-ha-cutover@v1.

References