NetBox Adapter

Relevant source files

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

• infrahub_sync/adapters/netbox.py
• examples/netbox_to_infrahub/config.yml
• examples/netbox_to_infrahub/netbox/sync_adapter.py
• dev/guidelines/writing-an-adapter.md
• dev/guides/adding-an-adapter.md
• dev/knowledge/adapter-anatomy.md
• dev/knowledge/sync-architecture.md

The NetBox Adapter extracts data from a NetBox instance to synchronize it with other systems, primarily Infrahub. It functions as a source connector that maps NetBox objects—such as devices, interfaces, and IP addresses—into a format compatible with the core sync engine. The adapter relies on the pynetbox SDK to communicate with the NetBox API.

Sources: README.md, dev/knowledge/sync-architecture.md, dev/guides/adding-an-adapter.md

Architecture and Components

The NetBox Adapter follows the standard infrahub-sync Adapter Anatomy. It consists of two main classes that extend the core diffsync framework with project-specific mixins.

• NetboxAdapter (DiffSyncMixin, Adapter): Manages the connection to NetBox and handles the loading of records.
• NetboxModel (DiffSyncModelMixin, DiffSyncModel): Defines the behavior of NetBox objects within the sync engine, including how they are created, updated, or deleted if the adapter acts as a destination.

The diagram shows the inheritance structure where NetBox-specific classes prioritize mixin methods over base DiffSync methods.
Sources: dev/guidelines/writing-an-adapter.md:7-14, dev/knowledge/adapter-anatomy.md:7-27, examples/netbox_to_infrahub/netbox/sync_adapter.py:38-42

Data Flow

The adapter executes a three-stage process to move data from NetBox to the sync engine's internal store:

1. Extraction: The model_loader identifies the target resource via the mapping key in config.yml (e.g., dcim.devices) and fetches records using the pynetbox client.
2. Processing: The adapter filters and transforms the raw API records using methods provided by DiffSyncModelMixin.
3. Conversion: A helper function (conventionally obj_to_diffsync) maps the processed fields to the DiffSync model, resolving references to other models.

The flow shows how NetBox API data is refined and converted before entering the sync engine.
Sources: dev/knowledge/adapter-anatomy.md:31-40, dev/guides/adding-an-adapter.md:54-62, dev/knowledge/sync-architecture.md:25-35

Configuration

The NetBox adapter requires specific settings in the config.yml file and environment variables for authentication.

Sync Configuration

The source block in the configuration file defines how the adapter connects to the NetBox instance.

Parameter	Type	Description
name	string	Set to netbox to use the built-in adapter.
settings.url	string	The base URL of the NetBox instance (e.g., https://demo.netbox.dev).

Sources: examples/netbox_to_infrahub/config.yml:23-28, dev/guides/adding-an-adapter.md:86-90

Environment Variables

To maintain security, the adapter retrieves credentials from the environment rather than hardcoded configuration.

Variable	Description
NETBOX_ADDRESS	The URL of the NetBox server. Overrides settings.url.
NETBOX_TOKEN	The API token used for authentication with NetBox.

Sources: dev/guidelines/writing-an-adapter.md:65-71, examples/netbox_to_infrahub/config.yml:33-37

Implementation Details

Model Loading

The model_loader function is the core of the extraction logic. It uses the pynetbox SDK to query specific endpoints defined in the schema mapping.

def model_loader(self, model_name, model):
    element = next(e for e in self.config.schema_mapping if e.name == model_name)
    records = self.client.get(element.mapping)
    
    # Filter and transform through the mixin helpers
    records = model.filter_records(records=records, schema_mapping=element)
    records = model.transform_records(records=records, schema_mapping=element)
    
    for obj in records:
        self.add(model(**self.obj_to_diffsync(obj=obj, mapping=element, model=model)))

Sources: dev/guides/adding-an-adapter.md:54-62, dev/guidelines/writing-an-adapter.md:18-24

Incremental Support

The NetBox adapter can participate in incremental synchronizations by implementing change tracking. It uses the cursor_tier_for method to signal support for timestamp-based or event-based changes.

• cursor_tier_for(model_name): Returns CursorTier.TIMESTAMP if the model supports last_updated filtering.
• list_changed_since(model_name, cursor): Fetches only those records updated after the provided cursor value using filters like last_updated__gte.

Sources: dev/knowledge/adapter-anatomy.md:38-42, dev/guides/adding-an-adapter.md:112-117, dev/guidelines/testing-adapters.md:32-38

Summary

The NetBox Adapter enables seamless data extraction from NetBox into the Infrahub ecosystem. By utilizing DiffSyncMixin and pynetbox, it provides a standardized way to filter, transform, and map complex network inventory data. Its design emphasizes security through environment-based credentials and performance via optional incremental sync support.