Skip to content

NetBox DB Cutover to PostgreSQL HA (HyOps Blueprint)

Purpose: Move NetBox DB connectivity from platform/onprem/postgresql-core to platform/onprem/postgresql-ha using a single governed blueprint run. This blueprint does not migrate data; run the NetBox DB migration workflow first when preserving existing records.
Owner: Platform engineering
Trigger: PostgreSQL HA is ready and NetBox should use HA as its primary DB backend
Impact: Reconciles NetBox against the PostgreSQL HA DB contract (inputs.db_state_ref=platform/onprem/postgresql-ha) after the target DB already contains the desired NetBox data.
Severity: P2
Pre-reqs: NetBox and PostgreSQL HA states in the cutover execution env (typically shared) are already ok, vault decrypt works, and runner can SSH to managed hosts.
Rollback strategy: Emergency rollback to pgcore is still possible, but now requires explicit override: db_state_ref=platform/onprem/postgresql-core plus allow_legacy_pgcore=true.

Context

Blueprint ref: onprem/netbox-ha-cutover@v1
Location: hybridops-core/blueprints/onprem/netbox-ha-cutover@v1/blueprint.yml

Execution flow:

  1. platform/onprem/netbox (cutover to HA DB state contract)

Note: This blueprint intentionally does not redeploy PostgreSQL HA or migrate NetBox DB contents. It consumes existing HA state and fails fast if HA is not ready. By default it resolves the HA DB contract from the same execution environment (--env, typically shared for NetBox authority). Advanced: you may override inputs.db_state_env to reference a different env during a controlled migration/test, but that is not the normal enterprise path.

Preconditions and safety checks

  • Confirm required states are available in the cutover env (usually shared):
  • platform/onprem/netbox
  • platform/onprem/platform-vm#platform_vms
  • platform/onprem/postgresql-ha
  • Confirm authority health before cutover:
hyops preflight --env shared --strict --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"
  • Validate HA state:
cat "$HOME/.hybridops/envs/shared/state/modules/platform__onprem__postgresql-ha/latest.json"

If HA is not ready yet, complete it first:

hyops blueprint deploy --env shared --ref onprem/postgresql-ha@v1 --execute

If existing NetBox data must be preserved, run migration before cutover:

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

Steps

  1. Validate and plan
hyops blueprint validate --ref onprem/netbox-ha-cutover@v1
hyops blueprint plan --env shared --ref onprem/netbox-ha-cutover@v1
  1. Run blueprint preflight
hyops blueprint preflight --env shared --ref onprem/netbox-ha-cutover@v1
  1. Execute cutover
hyops blueprint deploy --env shared \
  --ref onprem/netbox-ha-cutover@v1 \
  --execute

If HyOps detects existing step state (rerun/replacement risk), it may prompt for confirmation before executing the blueprint. Use --yes for non-interactive runs.

Verification

  • Check NetBox module state:
cat "$HOME/.hybridops/envs/shared/state/modules/platform__onprem__netbox/latest.json"
  • Confirm expected contract source in effective inputs/evidence:
  • inputs.db_state_ref=platform/onprem/postgresql-ha

  • inputs.db_state_env is unset (same-env default), unless you intentionally overrode it

  • Confirm HA state remains healthy:

cat "$HOME/.hybridops/envs/shared/state/modules/platform__onprem__postgresql-ha/latest.json"

Troubleshooting

  • contract failed: module state not ready:
  • Re-apply prerequisite modules and ensure both states are ok.
  • netbox authority ... not ready or API probe failures:
  • Ensure NetBox authority env is set correctly (HYOPS_NETBOX_AUTHORITY_ENV) and API/token are valid.
  • SSH connectivity errors:
  • Ensure L3 path/VPN or bastion settings are valid for the runner.

References