Infrahub Sync

Infrahub Sync synchronizes infrastructure data between Infrahub and external systems — NetBox, Nautobot, IP Fabric, Slurp’it, Cisco ACI, Peering Manager, ServiceNow-style CMDBs, and any system with a REST/JSON API. Define the synchronization declaratively in a configuration package, register an immutable version with the Sync API, and use the CLI or Python client to create and inspect service-owned runs.

Infrahub Sync is open source under Apache 2.0 and maintained on GitHub. V2 is available on PyPI. For private V3 testing, follow Install Infrahub Sync to get the candidate and its included CLI.

Infrahub Sync supports the following:

• Migration from an existing system of record — data moves from NetBox, Nautobot, or another source into Infrahub one model at a time, on the schedule the team chooses. The legacy system continues to operate during the migration.
• Recurring synchronization between systems — a sync project runs as often as the environment requires. Each run calculates a fresh diff and applies only the deltas.
• Inventory population from network discovery — adapters for IP Fabric and Slurp’it bring discovered network state into Infrahub as the source of truth, rather than requiring inventory to be entered by hand.
• Outbound data movement from Infrahub — Infrahub data is published into monitoring, observability, or CMDB systems that need a current view of infrastructure.
• Translation between data models — source fields map to destination fields through a declarative YAML configuration. Identifiers, relationships, and static values are handled in the same file.
• Diff preview before changes are applied — infrahub-sync diff shows the differences between source and destination state without modifying either system.

How it works

Concepts

• Configuration package — a JSON or YAML object that defines one synchronization between two systems. The Sync API registry assigns its configuration identity, version, and checksum.
• Adapter — the component that connects Infrahub Sync to a specific system. Each adapter handles both communication (API calls, authentication, request handling) and translation (converting the system's data into the internal sync engine's format). Infrahub Sync ships with adapters for common systems and supports custom adapters for systems without a pre-built one.
• Schema mapping — the part of the project configuration that defines how source fields map to destination fields. Direct field mappings, references between models, identifiers, and static values are all declared in YAML.

The core CLI workflow registers a package, creates a plan with diff, reviews it with runs plan, and either applies its checksum or creates a confirmed sync run.

Define a sync project

The package specifies the source adapter and destination adapter, execution order, and how each source field maps to a destination field. Credentials are references rather than embedded values. Submit the package with configs register; later runs use the returned configuration identity and version.

→ Create a sync project · Configuration package · Sync instance configuration

Preview with diff

infrahub-sync diff --config-id <id> --version <version> --reason <reason> creates a plan run through the Sync API. The destination is not modified. After the bounded wait succeeds, the CLI prints the saved summary and service checksum. runs plan <run-id> --detail reopens the same review after a detached admission.

Execute the sync

infrahub-sync sync --config-id <id> --version <version> --reason <reason> submits a confirmed synchronization. The service and worker calculate the plan and apply its write operations. When order is omitted, the engine derives dependency tiers from the schema mapping. When order is present, the configured sequence is used.

After a failed write, inspect the run record and destination before calculating a fresh plan. A failed operation can have written part of its change — unless the run records that it wrote nothing, which a refusal raised before its own write does. See Run a sync for recovery and convergence details.

Three diffsync_flags (SKIP_UNMATCHED_DST by default, SKIP_UNMATCHED_SRC, SKIP_MODIFIED) and per-mapping filters control what each run is allowed to change.

→ Run a sync · Sync CLI

Choose an execution surface

Surface	Use it for	Runtime requirements
CLI	Configuration and run operations through the Sync API	Included in the Compose image; run through the bundle
Python client	Typed access to every shipped Sync API resource	Compatible V3 Python package and Sync API access
Direct Prefect deployment	Starting and observing one plan or confirmed sync through Prefect's API	prefect extra and a Prefect server
Sync HTTP API	Authenticated remote runs, durable records and artifacts, reviewed apply, idempotency, and cancellation	service extra, Prefect, a work pool, a worker, and shared durable storage

Use the Python API, Prefect remote run, or Sync HTTP API reference for setup and contracts.

Who it's for

Implementing Infrahub alongside an existing system of record

Data lives in NetBox, Nautobot, IP Fabric, or another tool, and the team is adopting Infrahub. Infrahub Sync provides a path that does not require all teams to move at the same time, and that does not require writing integration code.

→ Install Infrahub Sync · Create a sync project

Operating Infrahub at steady state

Infrahub is deployed and needs to stay current with the other systems the team uses — IPAM, ITSM, monitoring, network discovery, or in-house databases. One sync project per source, run on the cadence the environment requires.

→ Create a sync project · Run a sync

Building inventory from network discovery

Infrahub is populated from what is actually deployed in the network rather than from manually curated inventory. IP Fabric and Slurp’it adapters connect to discovery tools and bring discovered state into Infrahub.

→ IP Fabric adapter · Slurp’it adapter

What's included

• Pre-built adapter library — adapters for Infrahub, NetBox, Nautobot, IP Fabric, Cisco ACI, LibreNMS, Observium, Peering Manager, Prometheus, and Slurp’it, plus a Generic REST API adapter for systems with HTTP/JSON APIs. Each adapter handles both communication and translation for its target system.
• Declarative YAML configuration — a single file per sync project defines source, destination, sync order, and per-model schema mapping. Mappings support 14 filter operations (including regex and is_ip_within), per-field transforms, custom Jinja filters, and ordered cross-reference resolution.
• Sync engine — built on the diffsync framework. Plans record deltas; three flags control what each run is allowed to change. Delete operations remain reviewable but are not executed.
• Typer-based CLI — configuration registry commands, diff and sync run admission, service plan review, and reviewed-checksum apply through one Sync API client.
• Custom adapter support — for systems without a pre-built adapter, write a custom adapter and declare it in the package's source.adapter as an installed dotted import path or an entry point. Registered execution loads only installed adapters, not a filesystem path.
• Custom CA certificate support — connect to systems with self-signed or internal CA-issued TLS certificates.

Adapter reference

Adapter	Direction supported
Infrahub	source or destination
NetBox	NetBox → Infrahub
Nautobot	Nautobot → Infrahub
IP Fabric	IP Fabric → Infrahub
Cisco ACI	Cisco ACI → Infrahub
Peering Manager	Peering Manager → Infrahub · Infrahub → Peering Manager
Prometheus	Prometheus → Infrahub
Slurp’it	Slurp’it → Infrahub
LibreNMS	LibreNMS → Infrahub
Observium	Observium → Infrahub
Generic REST API	external system → Infrahub

Get started

1. Prerequisites
   • A running Infrahub instance
   • A host meeting the Compose deployment requirements
   • Credentials and network access for the source and destination systems
2. Install Infrahub Sync. See Install Infrahub Sync: get the private candidate, start the Compose deployment, and run its included CLI.
3. Choose your starting point.
   • Setting up a sync project for the first time? → Create a sync project then Configuration package
   • Running an existing project? → Run a sync

Common questions

Do I have to migrate everything at once? No. Infrahub Sync is designed to move data one model at a time, on the team's own schedule. The legacy system keeps running throughout — there is no required cutover moment.

Does Infrahub Sync replace my scheduler? No. There is no built-in scheduler by design — the CLI submits diff and sync runs against the Sync API, so trigger it from whatever scheduling tooling the team already uses: cron, CI jobs, Prefect, Dagster, or similar.

What happens if a sync run fails partway through? Inspect the run record and destination before retrying. Calculate a fresh plan after a failed write. A failed operation can have written part of its change, unless the run records that it wrote nothing. The run recovery guidance explains how to interpret partial-write evidence and when to inspect the destination.

Can changes in the destination be overwritten by a sync? By default, SKIP_UNMATCHED_DST is enabled, which preserves destination objects that have no corresponding object in the source. For destination objects that do have a source match, the sync's behavior depends on the configured diffsync_flags. Decide upfront which system is authoritative for each model and configure the flags accordingly.

What if my source system doesn't have a pre-built adapter? Most systems with a REST/JSON API can use the Generic REST API adapter without modifications. For systems with non-standard APIs or custom logic requirements, write a custom adapter and register it as an installed adapter. See Local Adapters.

Can I run two sync projects at the same time? Yes. Each sync project is an independent registered configuration — its own package, configuration ID, and CLI invocation. Schedule and operate each project on its own cadence.

Additional resources

What you want to do	Where to go
Set up your environment	Install Infrahub Sync
Configure a sync project	Create a sync project · Sync instance configuration
Run a sync	Run a sync
Use the Python API	Python API
Run through Prefect	Prefect remote run
Operate the Sync HTTP API	Sync HTTP API
CLI reference	Sync CLI
All adapters	See the Adapters section in the sidebar
Custom CA certificates	Use custom CA certificates
Build a custom adapter	Local Adapters
Contribute	Contributing guide
Source code	github.com/opsmill/infrahub-sync