Pre-configured Adapters Overview

Relevant source files

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

• README.md
• dev/guides/adding-an-adapter.md
• dev/knowledge/sync-architecture.md
• dev/knowledge/adapter-anatomy.md
• dev/guidelines/writing-an-adapter.md
• AGENTS.md
• dev/knowledge/schema-mapping.md

Adapters serve as the synchronization layer connectors between Infrahub and external infrastructure systems. These components utilize the diffsync framework to load, compare, and reconcile data between a source and a destination system. Each adapter module resides in infrahub_sync/adapters/ and implements a specific contract to interact with external APIs or SDKs.

Sources: README.md:12-25, dev/knowledge/sync-architecture.md:7-16

Supported Built-in Adapters

The project includes several pre-configured adapters for common network and infrastructure tools. The Generic REST API adapter provides a baseline for connecting to any system featuring a standard REST interface.

Adapter	Supported Directions	Primary Use Case
Infrahub	Source or Destination	Core system of record for unified data.
NetBox	NetBox → Infrahub	Migration or continuous sync from NetBox.
Nautobot	Nautobot → Infrahub	Migration or continuous sync from Nautobot.
IP Fabric	IP Fabric → Infrahub	Discovery-driven inventory population.
Cisco ACI	Cisco ACI → Infrahub	SDN controller data synchronization.
Peering Manager	Bidirectional	Peering data management.
Prometheus	Prometheus → Infrahub	Observability data integration.
Slurp'it	Slurp'it → Infrahub	Network discovery integration.
Generic REST API	External → Infrahub	Custom REST-based system integration.

Sources: README.md:120-136, dev/guides/adding-an-adapter.md:12-16

Adapter Anatomy and Class Structure

Every adapter module defines two primary classes that inherit from both diffsync base classes and infrahub-sync mixins. The mixin must be declared before the base class to ensure proper method resolution.

Class Relationship Diagram

The diagram below illustrates the inheritance structure required for a functional adapter.

The diagram shows how custom adapters and models inherit from framework mixins and diffsync base classes.
Sources: dev/knowledge/adapter-anatomy.md:11-30, dev/guidelines/writing-an-adapter.md:10-20

Key Components

• Adapter Class (DiffSyncMixin): Manages the connection to the external system and implements the model_loader method.
• Model Class (DiffSyncModelMixin): Represents specific data types (e.g., Devices, VLANs) and handles create, update, and delete operations when acting as a destination.
• Type Attribute: Every adapter defines a type string (e.g., type = "NetBox") used for logging and source identification.

Sources: dev/knowledge/adapter-anatomy.md:32-60, dev/guidelines/writing-an-adapter.md:21-23

Data Flow and Orchestration

The Potenda engine orchestrates the interaction between adapters during a sync run. The engine executes three distinct phases: Load, Diff, and Sync.

Sync Execution Flow

This flowchart displays the standard three-phase synchronization process managed by the Potenda engine.
Sources: dev/knowledge/sync-architecture.md:27-40, dev/knowledge/adapter-anatomy.md:32-45

Phase Details

1. Load Phase: Potenda calls load() on both adapters. The adapters fetch data and use model_loader() to populate an in-memory store with DiffSyncModel instances.
2. Diff Phase: The engine compares the source store against the destination store to identify necessary changes.
3. Sync Phase: Potenda applies create, update, or delete operations to the destination adapter to achieve convergence.

Sources: dev/knowledge/sync-architecture.md:27-40, dev/knowledge/adapter-anatomy.md:32-45

Implementation Guidelines

Adapters must follow specific development standards to ensure safety and consistency across the ecosystem.

Core Rules

• Read-Only Safety: Adapters must provide functional list and diff pathways before enabling the mutating sync pathway.
• Optional Dependencies: External SDKs (e.g., pynetbox) are treated as optional dependencies. Use # ty: ignore[unresolved-import] and document the required install extra.
• Secret Handling: Credentials must come from environment variables or SyncConfig settings. Never hardcode, log, or print secrets.
• Filtering and Transformation: Always use model.filter_records() and model.transform_records() from the mixin to ensure consistent behavior with config.yml.

Sources: dev/guidelines/writing-an-adapter.md:25-33, 62-75, dev/constitution.md:20-30, AGENTS.md:85-100

Error Handling and Logging

Adapters must raise specific exceptions for authentication failures (401/403), timeouts, and pagination errors. The system uses structlog for structured logging.

# Standard pattern for adapter initialization and logging
import structlog
import os

class MysystemAdapter(DiffSyncMixin, Adapter):
    type = "MySystem"

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.log = structlog.get_logger()
        self.url = os.environ.get("MYSYSTEM_URL") or self.settings.get("url")
        # Do not log the token
        self.token = os.environ.get("MYSYSTEM_TOKEN") or self.settings.get("token")

Sources: dev/guidelines/writing-an-adapter.md:46-60, dev/guides/adding-an-adapter.md:42-55

Summary

Pre-configured adapters enable rapid integration between Infrahub and various infrastructure sources of truth. By adhering to the DiffSyncMixin contract and following strict security and implementation guidelines, these adapters ensure idempotent and predictable data synchronization across diverse environments.