Sync NetBox to Infrahub

This tutorial is for people getting started with Infrahub: it starts from a blank page, with no existing Infrahub instance or schema required. We will use Infrahub Sync to copy data from the public NetBox demo into Infrahub, installing and configuring everything we need along the way. This tutorial covers the fundamental work needed to get started; more advanced topics will be covered in subsequent guides.

Already running Infrahub?

If you already have an Infrahub instance running, you can skip straight to the NetBox adapter documentation.

By the end of this tutorial, you will know how to:

• run Infrahub and the Sync service locally
• install Infrahub Sync
• load a schema into Infrahub
• create a NetBox → Infrahub sync project
• synchronize NetBox objects into Infrahub
• review the import in a branch and open a proposed change

Time: ~30 minutes

What you will build: A running Infrahub instance with a production-grade schema covering the same core domains as NetBox (locations, devices, interfaces, IPAM, and organizations), populated with data synchronized from the public NetBox demo into a branch, ready to review as a proposed change.

Prerequisites:

• Docker installed and running (Docker Desktop or OrbStack)
• uv (Python package manager)
• Python 3.11+

Public demo data

The NetBox demo instance is public and resets regularly. Object counts, names, and sample data may differ from the examples in this tutorial. Because anyone can edit it, it can also contain malformed or unexpected data that breaks the sync — see Troubleshooting if you run into errors.

Create a project

Copier is a project scaffolding tool. Use it to create a new Infrahub project from the official template, which includes the standard file structure, task definitions, and a schemas/ folder:

1. Run the following command to create a new project directory:

uv tool run --from 'copier' copier copy https://github.com/opsmill/infrahub-template infrahub-automation

When prompted, enter a project name (for example, infrahub-automation), then press Enter to accept the default for every remaining prompt (they all default to No).

2. Navigate to the project directory:

cd infrahub-automation

3. Open the project in your IDE. If you have Visual Studio Code installed, you can run:

code .

Verification

Run ls in the project directory. You should see files including pyproject.toml, tasks.py, and a schemas/ folder.

Start Infrahub

The project template includes Invoke tasks that wrap Docker Compose commands.

1. Start all Infrahub services with a single command:

uv run invoke start

The first run takes a few minutes while Docker downloads the container images.

2. Open your browser and go to http://localhost:8000.

3. Log in from the bottom-left corner using the default credentials:

   • Username: admin
   • Password: infrahub

Verification

You should see the Infrahub web interface with a navigation menu on the left side.

Install infrahub-sync

1. Clone Infrahub Sync beside the automation project, then install the service profile from that checkout. The service profile is not published to PyPI yet, so the checkout keeps the executable, this tutorial, and its example package at one revision:

git clone https://github.com/opsmill/infrahub-sync.git ../infrahub-sync
uv add --editable "../infrahub-sync[service]" pynetbox

This installs the infrahub-sync command. pynetbox is required by the NetBox adapter.

2. Verify infrahub-sync command is available:

uv run infrahub-sync --help

For more about supported adapters and their Python requirements, see the NetBox adapter documentation.

Load a schema into Infrahub

Infrahub stores data according to its schema. Before we can import any data, we need Infrahub to know the kinds of objects that the sync will create.

We provide a production-grade Infrahub schema covering DCIM and IPAM features similar to NetBox's. It is not a one-to-one port of NetBox's own data model, and that's intentional.

info

This is a production-grade Infrahub schema, not a copy of NetBox's data model. Infrahub gives you a flexible graph model, so a real migration can preserve the parts of NetBox that matter to you while adapting the model to your own workflows.

This collection of schemas is maintained separately from Infrahub Sync. Download the exact source revision verified with this configuration so the destination kind names and relationships remain compatible:

SCHEMA_LIBRARY_REF="893be13f465158fdf49ce4133a501c8355d53a32"
DEST="schemas"
BASE_URL="https://raw.githubusercontent.com/opsmill/schema-library/${SCHEMA_LIBRARY_REF}"

FILES=(
  "base/dcim.yml"
  "base/location.yml"
  "base/ipam.yml"
  "base/organization.yml"
  "extensions/aggregate/aggregate.yml"
  "extensions/cable/cable.yml"
  "extensions/circuit/circuit.yml"
  "extensions/compute/compute.yml"
  "extensions/cluster/cluster.yml"
  "extensions/hosting_cluster/hosting_cluster.yml"
  "extensions/lag/lag.yml"
  "extensions/location_site/location_site.yml"
  "extensions/vlan/vlan.yml"
  "extensions/qinq/qinq.yml"
  "extensions/rack/rack.yml"
  "extensions/vrf/vrf.yml"
)

for f in "${FILES[@]}"; do
  curl -sSL --create-dirs -o "${DEST}/${f}" "${BASE_URL}/${f}"
done

Do not substitute models/examples/netbox/netbox.yml from the Infrahub source repository. Despite its similar name, it defines a different model whose kinds do not match this sync configuration.

Export the local Infrahub address and API token. Infrahub Sync will need them later to authenticate against your instance:

export INFRAHUB_ADDRESS="http://localhost:8000"
export INFRAHUB_API_TOKEN="06438eb2-8019-4776-878c-0941b1f1d1ec"

This is the default admin token that the project's Docker Compose stack seeds automatically, and it matches the default already configured in infrahubctl.toml. Do not reuse it for an internet-facing or shared Infrahub instance.

Then load the schema into Infrahub using the project's load-schema task:

uv run invoke load-schema

Refresh the local Infrahub web interface. You should see additional schema objects in the left navigation. You can also open the schema view in the UI to explore the kinds and relationships that were loaded.

Create a NetBox API token

Create a token in the public NetBox demo instance so Infrahub Sync can read data from NetBox.

1. Open the public NetBox demo.
2. Log in with username admin and password admin.
3. Open your user profile.
4. Create an API token.
5. Copy the complete generated token value.

Export the token locally:

export NETBOX_URL="https://demo.netbox.dev"
export NETBOX_TOKEN="nbt_..."

Export the complete nbt_... token value. Do not include an authorization prefix such as Bearer, and do not copy only the short Key field.

Create the sync project

A sync project is a directory containing a config.yml file. The configuration names the source and destination adapters, maps source fields to destination fields, and includes references that let Infrahub Sync compute write order.

From your project directory (infrahub-automation), create a sync project directory and download the example NetBox to Infrahub configuration.

mkdir -p sync-projects/netbox-demo
cp ../infrahub-sync/examples/netbox_to_infrahub/config.yml \
  sync-projects/netbox-demo/config.yml
cp ../infrahub-sync/examples/netbox_to_infrahub/package.yml \
  sync-projects/netbox-demo/package.yml

The copied configuration is named from-netbox. It maps selected NetBox objects onto the Infrahub schema.

Open sync-projects/netbox-demo/config.yml in an editor and scan the top-level keys:

• name identifies the sync project.
• source configures the NetBox adapter.
• destination configures the Infrahub adapter.
• schema_mapping defines how NetBox API resources become Infrahub objects.

The configuration includes default endpoint values, but the environment variables exported above take precedence for tokens and URLs.

This tutorial registers the package, uses diff to create a service plan, reviews that plan, and then submits a confirmed sync. See Run a sync when you need to apply the exact reviewed plan checksum instead of creating a new composed sync.

For a fuller explanation of this file, see Create a sync project and the schema mapping reference.

Start the Sync API and worker

The CLI sends configuration and run requests to a Sync API. A Prefect worker performs the adapter work. This local tutorial starts both; a production deployment should follow the Sync HTTP API reference.

Infrahub already listens on 127.0.0.1:8000, so the commands below bind the Sync API to 127.0.0.2:8000.

On macOS, create that loopback alias first with sudo ifconfig lo0 alias 127.0.0.2 up. If a process is bound to port 8000 on all interfaces, the second address cannot reuse that port; stop the conflicting process or start the Sync API on another port with uv run uvicorn --factory infrahub_sync.service.serve:build_app --host 127.0.0.2 --port 8001, then use that port in INFRAHUB_SYNC_API_URL.

1. Save this local service definition as sync-services.yml:

services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: sync
      POSTGRES_PASSWORD: sync-local-only
      POSTGRES_DB: infrahub_sync
    ports:
      - "127.0.0.1:5433:5432"
  minio:
    image: quay.io/minio/minio
    command: server /data
    environment:
      MINIO_ROOT_USER: sync-local
      MINIO_ROOT_PASSWORD: sync-local-secret
    ports:
      - "127.0.0.1:9000:9000"
  minio-client:
    image: quay.io/minio/mc
    entrypoint: /bin/sh
    command:
      - -c
      - until mc alias set local http://minio:9000 sync-local sync-local-secret; do sleep 1; done; mc mb --ignore-existing local/infrahub-sync-artifacts

Start PostgreSQL and MinIO, then create the artifact bucket:

docker compose -f sync-services.yml up --detach postgres minio
docker compose -f sync-services.yml run --rm minio-client

Wait until both containers report ready before continuing. These fixed values are local tutorial credentials; do not use them outside an isolated development machine.

2. In terminal 1, start Prefect:

uv run prefect server start --host 127.0.0.1 --port 4200

3. In each remaining service terminal, change to the infrahub-automation project root and export the shared service, storage, worker, and adapter settings:

export PREFECT_API_URL="http://127.0.0.1:4200/api"
export INFRAHUB_SYNC_DATABASE_URL="postgresql://sync:sync-local-only@127.0.0.1:5433/infrahub_sync"
export INFRAHUB_SYNC_S3_BUCKET="infrahub-sync-artifacts"
export INFRAHUB_SYNC_S3_ENDPOINT_URL="http://127.0.0.1:9000"
export INFRAHUB_SYNC_S3_REGION="us-east-1"
export AWS_ACCESS_KEY_ID="sync-local"
export AWS_SECRET_ACCESS_KEY="sync-local-secret"
export INFRAHUB_SYNC_SERVICE_WORK_POOL="sync-process-pool"
export INFRAHUB_SYNC_SERVICE_FLOW_WORKING_DIRECTORY="$PWD"
export INFRAHUB_SYNC_CONFIG_DIRECTORY="$PWD/sync-projects"
export INFRAHUB_SYNC_CACHE_DIR="$PWD/.infrahub-sync-cache"
export INFRAHUB_SYNC_SERVICE_BEARER_TOKENS='{"tutorial-admin":{"token":"tutorial-sync-api-token","administrator":true}}'
export NETBOX_URL="https://demo.netbox.dev"
export NETBOX_TOKEN="nbt_..."
export INFRAHUB_ADDRESS="http://localhost:8000"
export INFRAHUB_API_TOKEN="06438eb2-8019-4776-878c-0941b1f1d1ec"

Use the complete NetBox token created earlier. The worker, not the CLI, reads the NetBox and Infrahub adapter credentials. The package declares them as references — $credential entries under credentials naming NETBOX_TOKEN and INFRAHUB_API_TOKEN — so the worker resolves the values from these variables. No NetBox or Infrahub adapter credential value is written into the package or sent to the Sync API.

4. In terminal 2, create the process pool, deploy the service flow, and start its worker:

uv run prefect work-pool create --type process sync-process-pool
uv run python -m infrahub_sync.service.deploy
uv run python -m infrahub_sync.service.worker --pool sync-process-pool

5. In terminal 3, start the Sync API:

export INFRAHUB_SYNC_SERVICE_HOST="127.0.0.2"
uv run python -m infrahub_sync.service.serve

6. In the terminal where you will run the CLI, configure the API credentials and verify compatibility:

export INFRAHUB_SYNC_API_URL="http://127.0.0.2:8000"
export INFRAHUB_SYNC_API_TOKEN="tutorial-sync-api-token"
curl --fail "${INFRAHUB_SYNC_API_URL}/version"

The API token authenticates the CLI to the Sync API. It is separate from INFRAHUB_API_TOKEN, which the worker uses to access the destination Infrahub instance.

Register the configuration package

Register the downloaded package with the Sync API.

uv run infrahub-sync configs register sync-projects/netbox-demo/package.yml \
  --reason "register NetBox demo import"

Record the returned config_id and registry_version. If you edit the package later, use configs version <config-id> <package> to create another immutable registry version.

For more about the command flow, see Run a sync.

Create a branch

Infrahub tracks changes through branches, so you can review a batch of imported data as a proposed change before it lands on main. Create a branch to hold this import:

uv run infrahubctl branch create netbox-import

The rest of this tutorial runs diff and sync against this branch with --branch netbox-import, so you can inspect the destination changes before merging the Infrahub branch. For more about branches and proposed changes, see Infrahub version control.

Preview the changes

Run a dry-run diff against the netbox-import branch before writing any data to Infrahub.

uv run infrahub-sync diff \
  --config-id <config-id> \
  --version <version> \
  --branch netbox-import \
  --reason "review NetBox demo import"

The service worker loads NetBox and Infrahub, compares both sides, and publishes a saved plan. The CLI waits by default and prints its summary. Review it again with infrahub-sync runs plan <run-id> --detail. The sync command in the next step creates and applies a new plan; it does not apply this saved artifact.

Review the output before continuing. On a first run against an empty branch, most planned changes should be creates. Exact counts depend on the current public NetBox demo data.

Sync the data

After inspecting the diff, run the sync against the same branch. The worker loads both systems again, calculates a new plan, and writes it. The CLI prints the service-owned run state.

uv run infrahub-sync sync \
  --config-id <config-id> \
  --version <version> \
  --branch netbox-import \
  --reason "import NetBox demo data"

The first sync can take a few minutes because it writes the imported objects and relationships into the netbox-import branch — main is untouched until you merge the resulting proposed change. Because this configuration omits order:, Infrahub Sync derives the write order from the mapping references.

A second diff against this branch fails once interfaces exist

Once the sync has written interfaces, running diff or sync against the same branch again fails while loading the destination. This is a known defect, and it is not specific to NetBox. See diff fails after a sync that wrote interfaces for the error and how to get moving again.

Verify the imported data

The imported data lives on the netbox-import branch, not on main. Open the local Infrahub web interface:

1. Use the branch selector in the top-left corner to switch from main to netbox-import.

2. Browse the left navigation for imported objects from the NetBox demo. Depending on the current demo data and the example mapping, you may see objects such as:

   • tags and organizations (manufacturers, providers, RIRs)
   • sites and racks
   • devices and interfaces
   • VRFs, VLANs, and VLAN groups
   • prefixes, IP addresses, and aggregates
   • circuits
   This is a minimal mapping

   Some records and relationships may be missing — that doesn't mean the sync failed.

3. Once you're happy with the data, open a proposed change from netbox-import toward main so the import can be reviewed before it's merged.

If you switch back to main, none of this data is there yet — that's expected, since it's still isolated in the branch.

What happened

You used Infrahub Sync to move data from NetBox into Infrahub in a controlled sequence:

1. Infrahub provided the destination graph and schema.
2. NetBox provided the source data.
3. A branch isolated the import from main so it could be reviewed first.
4. config.yml described the adapters, field mappings, references, filters, and Transformations.
5. The Sync API registered the configuration and issued the run identity.
6. diff asked the worker to compare the source and destination without writing changes.
7. sync asked the worker to calculate and apply a new confirmed plan to the branch.

The same pattern applies to larger migrations: start with a clear schema, map a small set of objects, condition source data where needed, review the diff inside a branch, and then synchronize before opening a proposed change toward main.

Stop the local services

When you are finished, stop the API, worker, and Prefect processes with Ctrl-C. Then stop the Infrahub Docker Compose stack and remove the tutorial storage containers:

uv run invoke stop
docker compose -f sync-services.yml down

Troubleshooting

infrahub-sync fails with Both url and token must be specified

ERROR | infrahub_sync.cli | Failed to initialize the Sync Instance: Error initializing InfrahubAdapter: Both url and token must be specified!

The service worker cannot resolve a credential reference declared by the package. The package and config.yml contain credential references and declarations, but secret credential values belong only in the worker environment. The package names NETBOX_TOKEN and INFRAHUB_API_TOKEN, and the worker reads their values. Export these variables before starting the Prefect worker:

export NETBOX_URL="https://demo.netbox.dev"
export NETBOX_TOKEN="<your-netbox-token>"
export INFRAHUB_ADDRESS="http://localhost:8000"
export INFRAHUB_API_TOKEN="06438eb2-8019-4776-878c-0941b1f1d1ec"

This error names whichever adapter (NetBox or Infrahub) is missing its variables — the same message is raised for either one.

A plan run reports destination models missing from the schema

ERROR | One or more models are not present in the schema - ['LocationSite', ...]

The destination does not have the schema collection this configuration maps to. Download and load every file listed in Load a schema into Infrahub, then submit a new diff run. Use a fresh Infrahub instance or branch if an existing InfraDevice or another overlapping kind prevents that collection from loading.

The similarly named models/examples/netbox/netbox.yml file in the Infrahub source repository is not a replacement: it uses a different set of destination kinds.

infrahub-sync fails with Object ... already present

ValueError: An error occurred while loading Netbox: ('Object 172.16.0.2/24__Alpha already present', IpamIPAddress "172.16.0.2/24__Alpha")

Two source objects map to the same identifier — here, two IP addresses sharing an address and VRF. Delete one of the duplicates in NetBox (IPAM > IP Addresses, search the address from the message), then re-run the command.

diff fails after a sync that wrote interfaces

ValueError: An error occurred while loading Infrahub: Cannot build unique_id for peer
InterfaceLag[18c6…] (relationship InterfacePhysical.bundle, parent id=18c6…): missing
identifier key(s) ['device']; required identifiers=['device', 'name'], present
keys=['local_id', 'name', 'description', ...]

A first diff succeeds. Once a sync or apply has written an InterfacePhysical whose bundle points at an InterfaceLag, every later diff against that branch fails — while loading the destination, before any plan is produced. The message names Infrahub, not Netbox: the source is not involved. Deleting the interface objects at the destination restores normal behavior, and the cycle repeats.

The cause is that the destination loader rebuilds each related peer's identifier from a cached copy of the peer node, and the copy it finds carries the peer's attributes but not its relationships. InterfaceLag is identified by device and name, so its identifier cannot be rebuilt and the load aborts.

The client does not expose a control that changes worker extraction behavior. Delete the interface objects at the destination, correct the mapping or destination data, then create a new plan. Those objects are re-imported by the next confirmed sync.

Two things to be clear about:

• This is not a NetBox-specific defect, and it is not introduced by the saved-plan workflow. It affects any configuration in which a mapped kind references a peer kind whose identifiers include a relationship — the nautobot, ipfabric, slurpit, and aci example configurations all contain that shape.
• A source record that references a peer the source itself cannot resolve fails the whole run when the plan is derived. The client cannot soften that worker refusal.

Next steps

Now that you have completed a first sync, you have covered some of the basic objects in NetBox.

This is only the first step. You will likely want to bring in the parts that are unique to your own NetBox instance (for example, roles or custom fields).

Other guides will soon be available to cover:

• How to sync locations/regions
• How to deal with VLAN/Prefix/Device roles
• How to cover custom attributes / relationships
• Migrate configuration context