Project Overview

Relevant source files

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

• README.md
• dev/constitution.md
• AGENTS.md
• dev/knowledge/sync-architecture.md
• dev/knowledge/schema-mapping.md
• dev/guides/adding-an-adapter.md
• pyproject.toml

Infrahub Sync synchronizes data between infrastructure systems of record, such as NetBox, Nautobot, Cisco ACI, and Infrahub. It functions as a data synchronization layer that connects existing tools through per-system adapters and a core sync engine built on the diffsync framework. The system prioritizes safety, idempotency, and read-only pathways to prevent accidental corruption of production data.

The project utilizes a declarative YAML configuration to map fields between disparate data models. It supports 14 filter operations, per-field transforms using Jinja2 templates, and automated resolution of cross-reference dependencies.

Sources: README.md:9-16, dev/constitution.md:12-16, dev/knowledge/sync-architecture.md:6-10

Core Architecture

Infrahub Sync reconciles data from a source system to a destination system by loading objects into an in-memory store, calculating differences, and applying changes to the destination.

The Sync Pipeline

The synchronization process flows through three primary stages managed by the Potenda engine:

1. Load: The system concurrenty loads objects from both the source and destination into DiffSync stores.
2. Diff: The DiffSync comparison calculates create, update, and delete actions required to align the destination with the source.
3. Sync: The engine applies these actions to the destination in dependency order.

Key Components

Component	Responsibility
Potenda Engine	Orchestrates the load, diff, and sync stages; manages write tiers and incremental cursors.
Adapters	Connect specific systems (e.g., NetBox) to the engine; implement DiffSyncMixin.
Models	Represent typed records with natural keys (_identifiers) and comparable fields (_attributes).
Generator	Produces Python model classes from YAML configurations and destination schemas.

Sources: dev/knowledge/sync-architecture.md:15-22, dev/knowledge/sync-architecture.md:50-59

Core Principles and Safety

The system enforces strict development and operational standards to ensure infrastructure safety.

Safety Defaults

• Read-Only by Default: Commands like list, diff, and generate are non-mutating and safe to run at any time.
• Explicit Mutation: The sync command requires explicit user instruction and confirmed target servers.
• Idempotency: Re-running a sync on a converged environment must produce zero changes.
• Dry-Runs: A diff should always precede a sync to surface changes before they are applied.

Sources: dev/constitution.md:20-27, dev/constitution.md:32-40

Security Requirements

• Secrets Management: Credentials must come from environment variables or a secret manager; they are never committed, printed, or logged.
• Sanitization: Tracebacks and structured logs must not contain credentials.
• Isolation: Example configurations must use sanitized placeholders instead of real tokens or internal hostnames.

Sources: dev/constitution.md:73-81, AGENTS.md:104-108

Schema Mapping and Configuration

The schema_mapping block in config.yml defines how source resources translate to destination models.

Mapping Elements

Each entry in the mapping includes:

• name: The destination model/kind name.
• mapping: The source resource path (e.g., a REST collection or API endpoint).
• identifiers: The stable natural keys used for object identification.
• fields: Individual field mappings using static values, direct mapping paths, or reference resolution.

Field Logic and Transforms

Fields are processed in a specific priority:

1. Static: Assigns a literal value.
2. Mapping: Reads from the source record dot-notation path.
3. Reference: Resolves foreign keys to a peer object's unique_id.

Transforms use Jinja2 expressions to rewrite fields after filtering. These expressions run in a NativeEnvironment to preserve Python types like list or int.

Sources: dev/knowledge/schema-mapping.md:33-43, dev/knowledge/schema-mapping.md:65-71

CLI Commands

The Typer-based CLI provides four primary commands for managing synchronization projects.

Command	Safety	Purpose
list	Safe	Shows available sync projects in a directory.
diff	Safe	Computes differences between source and destination without writing.
generate	Safe	Generates Python model code from YAML configuration.
sync	Mutating	Applies changes to the destination system (requires approval).

Sources: AGENTS.md:63-68, dev/constitution.md:20-27

Development Workflow

Contributors must follow a standard workflow to maintain code quality and type safety.

Quality Gates

Before committing, developers must run the following Invoke tasks:

1. uv run invoke format: Formats code and Markdown.
2. uv run invoke lint: Executes Ruff, Pylint, Yamllint, and Ty.
3. uv run ty check .: Verifies type safety; no overrides are permitted in pyproject.toml.

Sources: AGENTS.md:31-36, dev/constitution.md:90-95

Adding Adapters

New adapters must inherit from DiffSyncMixin and DiffSyncModelMixin, declaring the mixin before the DiffSync base class. They must provide list and diff pathways before enabling sync.

Summary

Infrahub Sync provides a structured, safe, and declarative method for unifying infrastructure data. By leveraging a common sync engine and generated models, it ensures consistency across various adapters while maintaining strict operational safety through read-only defaults and idempotent executions.

Sources: README.md:9-12, dev/constitution.md:12-16