Skip to content

Operate NetBox Service (HyOps)

Purpose: Configure NetBox on an existing host using platform/onprem/netbox.
Owner: Platform engineering
Trigger: IPAM/inventory foundation bring-up, NetBox upgrade, or controlled environment rebuild
Impact: Creates or updates the NetBox service on the target host (Docker Compose)
Severity: P2
Pre-reqs: Reachable target host, PostgreSQL available, runtime vault decrypt working, Ansible deps installed.
Rollback strategy: Run hyops destroy with the same module and input overlay.

Context

This runbook covers module-level operations for:

  • Module: platform/onprem/netbox
  • Driver: config/ansible
  • Scope: configure NetBox on an existing Linux host (no VM provisioning)

NetBox requires PostgreSQL. Steady-state should consume platform/onprem/postgresql-ha through inputs.db_state_ref. Legacy platform/onprem/postgresql-core is now rollback-only and requires explicit opt-in (allow_legacy_pgcore=true).

Preconditions and safety checks

  • Installed hyops (via install.sh) can be run from any working directory.
  • If you want to use the shipped example overlays, set:
export HYOPS_CORE_ROOT="${HYOPS_CORE_ROOT:-$HOME/.hybridops/core/app}"

For source checkout usage, set HYOPS_CORE_ROOT to your hybridops-core checkout root instead. - Correct environment selected (--env shared|dev|staging|prod). Recommended: run the NetBox authority in --env shared. - Target host is reachable via SSH from the runner. - PostgreSQL is reachable from the NetBox host (db_host:db_port). - Ansible deps installed into the runtime root for the environment: - hybridops-core/tools/setup/setup-ansible.sh - Required secrets are available via shell env or runtime vault: - NETBOX_DB_PASSWORD - NETBOX_SECRET_KEY - Optional: NETBOX_SUPERUSER_PASSWORD - Optional (required for HyOps NetBox-authoritative IPAM workflows): NETBOX_API_TOKEN

Install/update Ansible runtime deps for the env:

# If you installed via install.sh (default runs setup-all), this is already done.
# To (re)install Ansible Galaxy deps for an env:
hyops setup ansible --env <env>

Steps

  1. Ensure PostgreSQL is ready

Preferred (HA):

HYOPS_INPUT_db_state_ref=platform/onprem/postgresql-ha \
hyops preflight --env <env> --strict \
  --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"

Temporary rollback (legacy pgcore):

HYOPS_INPUT_db_state_ref=platform/onprem/postgresql-core \
HYOPS_INPUT_allow_legacy_pgcore=true \
hyops preflight --env <env> --strict \
  --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"
  1. Select an overlay

Use one of:

  • $HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.min.yml
  • $HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml

  • $HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.enterprise.yml

  • Seed secrets (recommended: runtime vault)

hyops secrets set --env <env> \
  NETBOX_DB_PASSWORD='...' \
  NETBOX_SECRET_KEY='...' \
  NETBOX_SUPERUSER_PASSWORD='...' \
  NETBOX_API_TOKEN='...'
  1. Preflight
hyops preflight --env <env> --strict \
  --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"
  1. Deploy / converge
hyops apply --env <env> \
  --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"
  1. Optional: cut over NetBox DB contract to PostgreSQL HA

If platform/onprem/postgresql-ha is already status=ok, run:

hyops blueprint deploy --env shared \
  --ref onprem/netbox-ha-cutover@v1 \
  --execute

For direct module-level cutover (same effect), set:

HYOPS_INPUT_db_state_ref=platform/onprem/postgresql-ha \
hyops apply --env <env> \
  --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"
  1. Verify outputs and evidence
cat $HOME/.hybridops/envs/<env>/state/modules/platform__onprem__netbox/latest.json

Check:

  • status is ok
  • outputs.netbox_url is present

  • cap.ipam.netbox = ready is present

  • Destroy (best-effort cleanup)

hyops destroy --env <env> \
  --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"
  1. Rebuild (destroy then apply)
hyops rebuild --env <env> --yes \
  --confirm-module platform/onprem/netbox \
  --module platform/onprem/netbox \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/onprem/netbox/examples/inputs.typical.yml"

Verification

Primary state:

  • $HOME/.hybridops/envs/<env>/state/modules/platform__onprem__netbox/latest.json

Primary logs:

  • $HOME/.hybridops/envs/<env>/logs/module/platform__onprem__netbox/<run_id>/

Common issues

Port 8000 is already in use

Cause: netbox_http_host_port conflicts with an existing listener on the NetBox host.

Fix: set a free port in the overlay:

netbox_http_host_port: 8001

NetBox requires PostgreSQL but ... is not reachable

Cause: DB host/port unreachable from the NetBox host.

Fix:

  • Confirm routing/firewall allows db_host:5432.
  • Confirm PostgreSQL listens on the required interface and allowlists the NetBox host.

References