Skip to content

NetBox Export Hook Contract

Purpose

Defines the runtime contract for module-level execution.hooks.export_infra when using the Terragrunt driver and the HybridOps NetBox export/sync tooling.

Required runtime inputs

  • HYOPS_RUNTIME_ROOT: root for runtime state, logs, and records.
  • HYOPS_EXPORT_HOOK_ROOT: hook execution Terragrunt root (defaults to . from profile wiring).

NetBox API inputs (for sync/import tools)

  • NETBOX_API_URL
  • NETBOX_API_TOKEN
  • Optional fallback file: CONTROL_SECRETS_ENV (defaults to credentials/netbox.env under runtime root).

Hook execution contract

Terragrunt profile command MUST call:

python3 -m hyops.drivers.inventory.netbox.tools.export_infra --target {target} --terragrunt-root {hook_root} --only-module . --changed-only

Module opt-in contract:

execution:
  hooks:
    export_infra:
      enabled: true
      strict: false
      push_to_netbox: false
  • enabled: true runs export hook after successful apply.
  • strict: false records a warning on hook failure and does not fail apply.
  • strict: true fails apply when hook fails.

When push_to_netbox: true, fail-fast checks are enforced:

  • export hook command MUST succeed,
  • dataset (NETBOX_VMS_AUTO_JSON / NETBOX_VMS_AUTO_CSV) MUST exist and contain rows,
  • NETBOX_API_URL and NETBOX_API_TOKEN MUST be present,
  • profile netbox_sync_command MUST exist and return success.

Output paths

All paths are rooted at runtime root unless overridden:

  • state/netbox/vms/vms.auto.csv
  • state/netbox/vms/vms.auto.json
  • state/netbox/network/ipam-prefixes.csv
  • state/netbox/network/ipam-prefixes.json
  • logs/netbox/terraform/...
  • records/netbox/terraform/...

Validation commands

From hybridops-core:

  • PYTHONPYCACHEPREFIX=/tmp/hyops-pyc python3 -m compileall -q hyops
  • python3 -m hyops.drivers.inventory.netbox.tools.export_infra --list-targets

Dry-run style execution against a stack path:

  • HYOPS_RUNTIME_ROOT=/tmp/hyops-netbox-e2e PYTHONPATH=$(pwd) python3 -m hyops.drivers.inventory.netbox.tools.export_infra --target cloud-azure --terragrunt-root packs/iac/terragrunt/azure/core/00-foundation-global/10-resource-group@v1.0/stack --only-module . --changed-only

If no Terraform state exists yet, exporter reports no outputs or not deployed and exits successfully.