Nautobot Adapter

Relevant source files

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

• examples/nautobot-v2\_to\_infrahub/nautobot/sync\_adapter.py
• examples/nautobot-v1\_to\_infrahub/nautobot/sync\_adapter.py
• examples/nautobot-v2\_to\_infrahub/config.yml
• dev/knowledge/sync-architecture.md
• dev/knowledge/adapter-anatomy.md
• dev/guidelines/writing-an-adapter.md
• AGENTS.md

The Nautobot Adapter enables data synchronization between Nautobot instances and other infrastructure systems within the infrahub-sync ecosystem. It acts as a specialized connector that translates Nautobot's data structures into normalized DiffSync models. This adapter supports both Nautobot v1 and v2 environments, typically serving as a data source for migrations or continuous updates into Infrahub.

Sources: README.md:92, examples/nautobot-v2_to_infrahub/config.yml:4

Architecture and Class Hierarchy

The Nautobot adapter implements the DiffSyncMixin and Adapter base classes to participate in the sync engine. It manages a pynautobot client to interact with the Nautobot REST API. The adapter uses a dynamic loading mechanism where the PluginLoader resolves the specific adapter class at runtime.

The diagram shows the inheritance structure of the Nautobot adapter, highlighting its connection to core DiffSync and sync-specific mixins.

Sources: dev/knowledge/adapter-anatomy.md:8-25, examples/nautobot-v2_to_infrahub/nautobot/sync_adapter.py:31-34, dev/guidelines/writing-an-adapter.md:65

Core Components and Data Flow

The adapter operates within the Potenda engine, which orchestrates the loading, diffing, and synchronization phases. During the load phase, the adapter fetches records from Nautobot endpoints defined in the schema mapping.

Data Synchronization Flow

1. Load: The adapter fetches raw JSON records from Nautobot via REST API.
2. Transform: It applies Jinja2 transforms and filters defined in config.yml.
3. Map: The obj_to_diffsync logic converts raw records into DiffSync models.
4. Diff: The engine compares Nautobot models against the destination state.
5. Sync: The engine applies changes to the destination system.

This flowchart illustrates the transition of data from the Nautobot source through the transformation layer into the sync engine.

Sources: dev/knowledge/sync-architecture.md:23-38, dev/knowledge/adapter-anatomy.md:69-76

Configuration and Schema Mapping

Configuration occurs in config.yml, where users define connection settings and how Nautobot resources map to destination models. The schema_mapping block specifies the endpoint, identifiers, and field-level translations.

Connection Settings

Parameter	Type	Description
url	String	The base URL of the Nautobot instance.
token	String	REST API authentication token.

Sources: examples/nautobot-v2_to_infrahub/config.yml:3-7

Example Model Mappings

The adapter supports a wide range of Nautobot resources, including devices, circuits, and IPAM data.

Nautobot Resource	Destination Model	Identifiers
dcim.devices	InfraDevice	location, organization, name
ipam.prefixes	InfraPrefix	prefix, ip_namespace
extras.tags	BuiltinTag	name
dcim.locations	LocationGeneric	name

Sources: examples/nautobot-v2_to_infrahub/config.yml:44-245

Model Generation and Implementation

Adapters in infrahub-sync do not require hand-written model classes for every object. Instead, the infrahub-sync generate command reads the schema_mapping and renders Python model classes from templates.

class NautobotSync(_AdapterBaseClass):
    CoreStandardGroup = CoreStandardGroup
    BuiltinTag = BuiltinTag
    InfraDevice = InfraDevice
    InfraPrefix = InfraPrefix
    InfraVLAN = InfraVLAN
    # ... additional models assigned to the adapter

Sources: examples/nautobot-v2_to_infrahub/nautobot/sync_adapter.py:34-60, dev/knowledge/sync-architecture.md:46-55

Transformation Logic

The adapter handles data differences between Nautobot versions using Jinja2 expressions. For example, it can transform Nautobot v2 "NULL" status values into a standard "default" label.

  - name: StatusGeneric
    mapping: extras.statuses
    transforms:
      - field: new_name
        expression: "{{ 'default' if name == 'NULL' else name }}"

Sources: examples/nautobot-v2_to_infrahub/config.yml:83-85

Summary

The Nautobot Adapter provides a robust bridge between Nautobot and the Infrahub ecosystem. By utilizing a declarative YAML configuration and the diffsync framework, it allows for complex data migrations and state reconciliations without custom integration code. Its reliance on structured logging via structlog and secure credential handling via environment variables ensures production-ready reliability.

Sources: AGENTS.md:124, dev/constitution.md:104, dev/knowledge/sync-architecture.md:10-15