---
title: Infrahub adapter
---

import ReferenceLink from "../../src/components/Card";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<!-- vale off -->
## What is Infrahub?
<!-- vale on -->

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](https://pypi.org/project/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

<Tabs>
  <TabItem value="destination" label="As Destination" default>

  ```yaml
  ---
  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
  ```

  </TabItem>
  <TabItem value="source" label="As Source">

  ```yaml
  ---
  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>"
  ```

  </TabItem>
</Tabs>

### 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

```yaml
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

```yaml
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:

```yaml
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:

```bash
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

<!-- vale Infrahub.sentence-case = NO -->
### SSL certificate issues
<!-- vale Infrahub.sentence-case = YES -->

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