Installation & Quickstart

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pyproject.toml
• AGENTS.md
• dev/constitution.md
• dev/guides/adding-an-adapter.md
• RELEASING.md

Infrahub Sync synchronizes infrastructure data between a source and a destination system using specialized adapters and a YAML-based configuration. It provides a Typer-based Command Line Interface (CLI) to manage migrations, continuous synchronization, and inventory publishing across systems like NetBox, Nautobot, and Cisco ACI.

This page guides you through setting up the environment, installing the package, and executing your first synchronization project.

Prerequisites

Before installing Infrahub Sync, ensure your environment meets the following requirements:

• Python Version: Python 3.10, 3.11, 3.12, or 3.13 is required.
• Infrastructure: A running instance of Infrahub or another supported destination system.
• Connectivity: Network access and valid credentials (API tokens, URLs) for both source and destination systems.

Sources: README.md:46-48, pyproject.toml:9

Installation Methods

Standard Installation (PyPI)

For general use, install the package from PyPI into a virtual environment.

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the package
pip install infrahub-sync

# Verify the installation
infrahub-sync --help

Sources: README.md:55-63

Development Installation

If you intend to contribute or develop new adapters, use uv for dependency management.

1. Clone the repository.
2. Install uv.
3. Run uv sync to install the project and its development dependencies.

Sources: AGENTS.md:19-22

Dependency Summary

Infrahub Sync relies on several core libraries to perform data transformations and synchronization.

Dependency	Purpose	Version Requirement
infrahub-sdk	Communication with Infrahub	>=1.17, <2
diffsync	Core synchronization engine	[redis]>=2.1, <3.0
typer	CLI framework	>=0.23.1
pydantic	Data validation and configuration	>=2.10.2, <3
structlog	Structured logging	>=25.1, <27.0

Sources: pyproject.toml:17-32

Initializing a Sync Project

A sync project requires a directory containing a config.yml file. This file defines the source, destination, and the schema mapping between them.

Project Directory Structure

A typical project structure follows this pattern:

my_sync_project/
├─ config.yml            # Synchronization settings
└─ custom_adapters/      # (Optional) Local adapter code

Sources: AGENTS.md:40-50, dev/guides/adding-an-adapter.md:88-105

Configuration Components

The configuration defines the data flow and transformation rules.

Key	Description
name	Unique identifier for the sync project.
source	Specifies the adapter name and connection settings for the data origin.
destination	Specifies the adapter name and connection settings for the data target.
schema_mapping	Lists destination models and how source fields map to them.
order	(Optional) Explicit sequence for object synchronization.

Sources: AGENTS.md:59-62, dev/guides/adding-an-adapter.md:92-105

Command Workflow

Infrahub Sync follows a safety-first philosophy where non-mutating actions are preferred before applying changes.

Synchronization Flow Diagram

The following diagram illustrates the standard operational sequence from discovery to execution.

The workflow ensures that the destination system is only modified after a manual review of the calculated differences.
Sources: dev/constitution.md:20-27, AGENTS.md:52-57

Core CLI Commands

1. list: Scans a directory to find and display available sync projects.
2. generate: Generates Python model classes from the YAML configuration. This step requires access to the destination server to fetch schema definitions.
3. diff: Compares the source and destination data. It displays the specific Create, Update, or Delete actions that would occur.
4. sync: Executes the changes on the destination system. This command requires explicit instruction and user approval.

Sources: AGENTS.md:52-57, dev/constitution.md:21-25

Quickstart Example: NetBox to Infrahub

To run the provided example pull data from a NetBox demo instance:

1. Identify the Project: Use the from-netbox project located in the examples/ directory.
2. Generate Models: Create the necessary Python classes for the sync.

   infrahub-sync generate --name from-netbox --directory ./examples
   

3. Preview Changes: View the differences between NetBox and your local Infrahub.

   infrahub-sync diff --name from-netbox --directory ./examples
   

4. Execute Sync: Apply the changes to the destination.

   infrahub-sync sync --name from-netbox --directory ./examples
   

Sources: README.md:69-79

Safety and Operational Principles

Infrahub Sync adheres to strict operational standards to prevent data corruption.

• Dry-Run by Default: Commands like list, diff, and generate are non-mutating and safe to run against production environments at any time.
• Explicit Approval: The sync command must never run as a side effect and always requires confirmation.
• Secret Hygiene: Credentials must come from environment variables or secret managers. They are never printed in logs, tracebacks, or committed to version control.
• Idempotency: Re-running a sync on converged systems produces no changes.

Sources: dev/constitution.md:20-41, AGENTS.md:63-65

Summary

Infrahub Sync provides a structured approach to infrastructure data management. By installing the package and following the list -> generate -> diff -> sync workflow, users can safely transition data between systems while maintaining visibility and control through declarative YAML configurations.