Skip to content

Source of Truth: NetBox-Driven Inventory

Status: Accepted

NetBox is the single source of truth (SoT) for infrastructure topology, device metadata, and automation inventory across on-premises and cloud environments.

1. Context

The platform needs a consistent and authoritative representation of:

  • Sites, VLANs, prefixes, and IP addresses.
  • Devices, VMs, and services across dev / staging / prod.
  • Relationships used by automation (for example, which IP belongs to which VM).

Static INI/YAML inventories drift as clusters change. Re-modeling state in multiple places (Terraform, Ansible, diagrams, documentation) creates inconsistencies and weakens the DR and audit story.

A central SoT is required so that:

  • Automation targets are always derived from the same model.
  • DR rehearsals and re-builds can reconstruct inventory deterministically.
  • Evidence (logs, diagrams, exports) can point back to a single authority.

2. Decision

Adopt NetBox as the authoritative source of truth for:

  • IPAM (prefixes, addresses, IP roles).
  • DCIM / virtualization objects (devices, VMs, interfaces).
  • Relationships used for automation (for example, tags, roles, tenants).

Automation systems consume NetBox rather than re-implementing inventory:

  • Ansible uses NetBox-backed dynamic inventory.
  • Terraform / Terragrunt reads selected data from NetBox (where required) and publishes additional context when appropriate.
  • Custom helpers (for example, infrastructure export/import scripts) ensure that platform state and NetBox remain aligned.

Authoring rule: inventory and addressing decisions are expressed in NetBox; code and playbooks read from that model.

3. Architecture overview

NetBox sits between IaC, automation, and the runtime infrastructure.

View NetBox source-of-truth overview diagram 
graph TD
  subgraph Infra ["Infrastructure & IaC"]
    TF["Terraform / Terragrunt<br/>(Proxmox, cloud)"]
    PX["Proxmox / RKE2 clusters"]
  end

  subgraph Automation ["Automation & CI"]
    AN["Ansible playbooks<br/>+ dynamic inventory"]
    CJ["Jenkins / CI pipelines"]
  end

  subgraph SoT ["Source of Truth"]
    NB["NetBox (IPAM + DCIM)"]
  end

  subgraph Secrets ["Secrets & Access"]
    AKV["Azure Key Vault<br/>(platform secrets)"]
    SE["control/secrets.vault.env<br/>(projected env vars)"]
  end

  TF --> NB
  PX --> NB
  CJ --> NB

  NB --> AN
  NB --> CJ

  AKV --> SE
  SE --> CJ
  SE --> AN

  AN --> PX

4. Implementation

4.1 Bootstrap before NetBox exists

During initial bring-up, PostgreSQL and NetBox do not yet exist. A temporary, static inventory is used to get them online:

  1. Terraform / Terragrunt provisions static-IP core VMs on Proxmox:
  2. ctrl01
  3. pg-core
  4. netbox
  5. The helper script control/tools/helper/netbox/export_infra.py:
  6. Calls terragrunt output across on-prem stacks.
  7. Writes deployment/inventories/netbox/infrastructure.csv (VMs and IPs).
  8. Writes deployment/inventories/core/bootstrap.ini for Ansible bootstrap.
  9. Ansible playbooks (for example deployment/ansible/playbooks/bootstrap/postgres-setup.yml and deployment/ansible/playbooks/bootstrap/netbox-setup.yml) run against core/bootstrap.ini to install PostgreSQL and NetBox.

NetBox is then reachable at a known address, with its admin password and API token stored in Azure Key Vault via the Key Vault foundation module.

4.2 Seeding NetBox from CSV

Once NetBox is online, it is populated from the exported infrastructure CSV:

  1. On ctrl01, secrets for NetBox API access are projected from Azure Key Vault into control/secrets.vault.env via control/tools/helper/secrets/sync_from_akv.sh as defined in ADR-0020.
  2. The NetBox seed playbook deployment/netbox/playbooks/seed.yml:
  3. Calls export_infra.py to refresh infrastructure.csv.
  4. Calls control/tools/helper/netbox/import_infra_to_netbox.py to create or update VM and IP objects in NetBox, and set primary IPs.

NetBox now reflects the Proxmox VMs and their primary IP addresses and can be treated as authoritative for IPAM and VM inventory.

4.3 NetBox-backed dynamic inventories

After NetBox is seeded, Ansible inventories pivot to NetBox:

  • deployment/inventories/core/netbox.yml provides a core/control-plane view (for example ctrl01, pg-core, netbox, core RKE2 nodes).
  • deployment/inventories/env/*/netbox.yml provides environment-scoped views (dev, staging, prod) using environment-specific filters and grouping rules.

Ansible playbooks for day-2 operations (RKE2, platform add-ons, application deployments) use these NetBox-backed inventories rather than static host lists.

Terraform and other tooling may also consume NetBox data where appropriate, but NetBox remains the inventory authority, not a passive reporting target.

5. Consequences

Benefits

  • Single, API-driven SoT for IPAM and inventory.
  • Reduced drift between infrastructure, automation, and documentation.
  • Clear audit trail: exported CSVs, NetBox records, and Ansible logs can all be cross-referenced.
  • Strong story for assessors: inventories are not hand-maintained INI files.

Trade-offs and constraints

  • NetBox availability becomes an operational dependency for day-2 automation.
  • The data model must be maintained with discipline (prefixes, roles, tags).
  • Additional bootstrap steps are required before NetBox exists, handled via the export/import helper scripts and bootstrap playbooks.

6. Validation and evidence

Evidence that NetBox is acting as the SoT includes:

  • Export and seed scripts under:
  • control/tools/helper/netbox/export_infra.py
  • control/tools/helper/netbox/import_infra_to_netbox.py
  • NetBox seed playbook:
  • deployment/netbox/playbooks/seed.yml
  • Inventory layout and usage:
  • deployment/inventories/core/netbox.yml
  • deployment/inventories/env/*/netbox.yml
  • Secrets projection path from Azure Key Vault to ctrl01:
  • control/tools/helper/secrets/sync_from_akv.sh
  • control/secrets.vault.env (derived, not version-controlled)
  • Run artefacts and logs under:
  • output/artifacts/netbox/ (NetBox bootstrap and seed runs).

These locations are also referenced from the documentation site and the evidence map for the platform.

7. References

Maintainer: HybridOps.Studio
License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.