Infrahub adapter

What is Infrahub?

Infrahub is an open-source infrastructure management platform that combines a version-controlled database with a schema-driven data model. It serves as the central hub for network automation, providing a single source of truth for infrastructure data.

Requirements

This adapter uses the Infrahub SDK, which is included as a dependency of infrahub-sync.

Sync directions supported

• Source: Infrahub can be used as a data source
• Destination: Infrahub is the primary destination for most sync configurations

info

The Infrahub adapter supports bidirectional synchronization. Most commonly, Infrahub is used as the destination, receiving data from other systems like NetBox, Nautobot, or IP Fabric.

Configuration

The adapter reads connection settings from the synchronization configuration and can be overridden by environment variables.

Configuration parameters

As Destination

---
name: from-netbox
source:
  name: netbox
  settings:
    url: "https://<NETBOX-ENDPOINT>"
    token: "<TOKEN>"

destination:
  name: infrahub
  settings:
    url: "http://localhost:8000"
    token: "<INFRAHUB_TOKEN>"  # Optional if using env var
    branch: "main"            # Optional, defaults to main
    verify_ssl: true          # Optional, defaults to true
    source: "data-sync"       # Optional, CoreAccountGroup name for lineage source
    owner: "network-team"     # Optional, CoreAccountGroup name for lineage owner

As Source

---
name: to-peering-manager
source:
  name: infrahub
  settings:
    url: "http://localhost:8000"
    token: "<INFRAHUB_TOKEN>"
    branch: "main"

destination:
  name: peeringmanager
  settings:
    url: "https://<PM-ENDPOINT>"
    token: "<TOKEN>"

Environment variables

Variable	Description
INFRAHUB_ADDRESS or INFRAHUB_URL	Infrahub server URL (overrides settings.url)
INFRAHUB_API_TOKEN	API token for authentication (overrides settings.token)

Settings reference

Setting	Type	Required	Default	Description
url	string	Yes*	-	Infrahub server URL
token	string	Yes*	-	API token for authentication
branch	string	No	main	Target branch for operations
verify_ssl	boolean	No	true	Verify SSL certificates
source	string	No	-	CoreAccountGroup name to use as lineage source
owner	string	No	-	CoreAccountGroup name to use as lineage owner

*Can be provided via environment variables instead.

Schema mapping

When Infrahub is used as a destination, the schema mapping defines how source data maps to Infrahub node types. The name field in schema_mapping corresponds to the Infrahub schema kind.

Basic example

schema_mapping:
  - name: InfraDevice
    mapping: dcim.devices
    identifiers: ["name"]
    fields:
      - name: name
        mapping: name
      - name: description
        mapping: description
      - name: status
        mapping: status.value

  - name: InfraInterface
    mapping: dcim.interfaces
    identifiers: ["device", "name"]
    fields:
      - name: name
        mapping: name
      - name: device
        mapping: device.name
        reference: InfraDevice

Relationship handling

The Infrahub adapter automatically resolves relationships based on the schema:

• One-to-one relationships: Resolved using the unique identifier of the related node
• One-to-many relationships: Resolved as a list of unique identifiers

fields:
  # One-to-one relationship
  - name: site
    mapping: site.name
    reference: LocationSite

  # One-to-many relationship
  - name: tags
    mapping: tags
    reference: BuiltinTag

Lineage tracking

When syncing data into Infrahub, the adapter tracks the source and owner of each record using Infrahub's lineage system. This enables:

• Tracking which system created each record
• Protecting source-managed attributes from manual edits
• Assigning ownership to teams or groups

Default behavior

By default, the adapter looks for a CoreAccount with a name matching the source adapter name. This account is used as both the source and owner for all synced attributes.

Using account groups

You can override the default behavior by specifying source and/or owner in the destination settings. When specified, these values are used to look up a CoreAccountGroup by name:

destination:
  name: infrahub
  settings:
    url: "http://localhost:8000"
    token: "<TOKEN>"
    source: "data-sync"      # Uses CoreAccountGroup "data-sync" as source
    owner: "network-team"    # Uses CoreAccountGroup "network-team" as owner

This allows you to:

• Use different groups for source and owner
• Override only one while keeping the default account for the other
• Assign ownership to a team rather than an individual account

Configuration	Source	Owner
Neither specified	CoreAccount (source name)	CoreAccount (source name)
Only source specified	CoreAccountGroup	CoreAccount (source name)
Only owner specified	CoreAccount (source name)	CoreAccountGroup
Both specified	CoreAccountGroup	CoreAccountGroup

Generating the models

Use the generate command to produce Python models from your configuration:

poetry run infrahub-sync generate --name from-netbox --directory examples/

Common issues and troubleshooting

Authentication errors

• Verify INFRAHUB_API_TOKEN is set correctly
• Ensure the token has appropriate permissions for the target branch
• Check that INFRAHUB_ADDRESS points to the correct server

Schema mismatch errors

• Ensure your Infrahub schema matches the expected node types in schema_mapping
• Run infrahubctl schema load to update the schema if needed
• Verify field names match the Infrahub schema attribute names

Relationship resolution failures

• Ensure referenced objects are synced before objects that reference them (check order in configuration)
• Verify the unique identifier used in references matches the target object's identifier
• Check logs for "Unable to find ... in the Store" messages

Branch operations

• Verify the target branch exists in Infrahub
• Use infrahubctl branch list to see available branches
• Create branches with infrahubctl branch create <name> if needed

SSL certificate issues

• Set verify_ssl: false in settings for self-signed certificates (development only)
• For production, ensure proper CA certificates are installed