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. Use it to migrate from a legacy system of record, run two systems side-by-side, or keep Infrahub in sync with another source of truth. Define a sync project declaratively in YAML, and the CLI generates the adapter code, calculates the diff, and applies only the deltas on each run.

Infrahub Sync is open source under Apache 2.0, distributed on PyPI, and maintained on GitHub.

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

• Sync project — a directory containing a YAML configuration file (config.yml) that defines one synchronization between two systems. A project specifies the source, the destination, the sync order, and the per-model schema mapping. A team can have many sync projects, each managing a different source-destination pair.
• 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 uses generate, diff, and either apply or sync. The list command discovers projects before that workflow begins.

Define a sync project

Each sync project consists of a directory and a config.yml describing the sync. The configuration specifies the source adapter and destination adapter with their connection details, the order in which models should be synchronized, and how each source field maps to a destination field. Credentials reference environment variables rather than being embedded in the file.

→ Create a sync project · Sync instance configuration

Generate the adapter code

infrahub-sync generate --name <project> --directory <dir> reads the YAML configuration and produces the Python adapter and model code that diff and sync use. Re-run generate whenever the configuration or the schema mapping changes.

Preview with diff

infrahub-sync diff --name <project> --directory <dir> reads both the source and destination, calculates what would change, and prints the result to the terminal. The destination is not modified. The diff command is read-only and is typically run before applying any sync — particularly during initial setup or when adjusting mappings.

Execute the sync

infrahub-sync sync --name <project> --directory <dir> calculates a plan and applies 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, and safe re-application is not established for destination kinds whose identity crosses a relationship. 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	Interactive and scheduled operations, including saved-plan review and apply	Base installation plus adapter dependencies
Python API	Typed in-process plan, verify, apply, and confirmed sync operations	Base installation plus adapter dependencies
Direct Prefect deployment	Starting and observing one plan or confirmed sync through Prefect's API	prefect extra and a Prefect server
Managed Sync HTTP API	Authenticated remote runs, durable records and artifacts, reviewed apply, idempotency, and cancellation	managed extra, Prefect, a work pool, a worker, and shared durable storage

Use the Python API, Prefect remote run, or managed 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 — five commands: list (show available projects), generate (produce adapter code from the configuration), diff (preview changes), sync (apply changes), apply (write a previously reviewed saved plan to the destination without re-extracting the source).
• Custom adapter support — for systems without a pre-built adapter, write a local custom adapter and load it from a filesystem path, a Python module path, or an installed entry point (INFRAHUB_SYNC_ADAPTER_PATHS).
• 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
   • Python 3.10–3.13
   • Credentials and network access for the source and destination systems
2. Install Infrahub Sync. See Install Infrahub Sync for the full setup steps. The short version: pip install infrahub-sync into a virtual environment.
3. Choose your starting point.
   • Setting up a sync project for the first time? → Create a sync project
   • 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. Infrahub Sync runs as a CLI and is designed to plug into whatever scheduling tooling the team already uses — cron, CI jobs, Prefect, Dagster, or similar. There is no built-in scheduler by design.

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, and destination kinds whose identity crosses a relationship may not converge safely when reapplied. 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, build a local custom adapter. See Local Adapters.

Can I run two sync projects at the same time? Yes. Each sync project is independent — a separate directory, configuration, 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 managed HTTP API	Managed 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