Skip to content

Infrahub Device Sync

Infrahub logo
Device Sync integrationInfrahub
Lab tested

Infrahub Device Sync: End-to-End Setup in rConfig V8.2.0

Section titled “Infrahub Device Sync: End-to-End Setup in rConfig V8.2.0”

The V2 Infrahub driver pulls device inventory from an Infrahub instance using its GraphQL API and feeds the results through the unified V2 pipeline. This guide follows the same model as the Statseeker V2 setup: only the Setup tab fields and upstream-side conventions are different.

Platform rConfig V8 Support Auth supported V2 Status
Infrahub V8.2.0+ API token Lab tested

The point of setting up a V2 integration is to land in a steady state where rConfig’s device inventory is continuously reconciled against Infrahub on a schedule, with no operator in the loop. That end state looks like this:

A Scheduled Task of type Integration V2 Job runs the Infrahub instance in Apply mode on a cron, e.g. nightly. It runs the same six-stage pipeline you’ll run interactively in this guide, writes any create and update decisions to rConfig, leaves any conflicts or ambiguous matches in Problem Devices for review, and notifies you on completion.

To get there, you walk a one-time setup and a sanity-check loop:

  1. Create the integration instance: Infrahub connectivity, GraphQL query and auth in the Setup tab. Validate with Test Connection.
  2. Set a Default Device Profile. Infrahub does not surface per-device profile metadata in the default schema, so devices take the instance’s Default Device Profile (V8.4.3 and later).
  3. Run an Extract Preview to confirm your GraphQL query returns the right Infrahub devices.
  4. Run a Sync Preview to walk the full pipeline (canonicalize → reconcile → decide) without writing.
  5. Run a Full Sync (Apply) once the preview’s decisions look right.
  6. Schedule the integration to run on a cron from the rConfig scheduler.
%%{init: {'themeVariables': {'fontSize': '60px'}}}%%
flowchart LR
    A[Create instance<br/>Setup tab] --> B[Test Connection]
    B --> C[Device Profiles<br/>Inventory]
    C --> D[Extract Preview]
    D --> E[Sync Preview]
    E --> F[Full Sync · Apply]
    F --> G[Scheduled Task<br/>recurring sync]

  classDef step font-size:60px,stroke-width:2px;
  class A,B,C,D,E,F,G step;

Infrahub:

  • A reachable Infrahub instance with the GraphQL API enabled at /graphql
  • An API token for a service account with read access to the configured root field (default InfraDevice)
  • Network connectivity from rConfig to Infrahub
  • A working knowledge of Infrahub GraphQL: the default query covers the standard InfraDevice schema, but you may need to adjust it for your data model

rConfig V8.2.0+:

  • Administrator access
  • rConfig V8.4.3 or later to create devices. The default Infrahub schema has no profile-slug attribute, so every device takes the instance’s Default Device Profile, which arrived in V8.4.3 (see Step 2).

Step 1: Create the Integration Instance (Setup Tab)

Section titled “Step 1: Create the Integration Instance (Setup Tab)”

Navigate to Platform → Integrations. Scroll to the Device Sync section and click + Add Driver under V2 Drivers.

V2 driver picker (Platform → Integrations → Device Sync → Add Driver) with Infrahub highlighted

The Infrahub card carries a Lab tested badge: click it to open the Setup tab.

The form is rendered from infrahub.schema.php and is laid out in two sections.

Infrahub Setup tab with Connectivity and Authentication sections expanded

Connectivity

Field Default Notes
Base URL required Root of the Infrahub instance, e.g. https://infrahub.example.com. No trailing slash needed.
GraphQL Path /graphql Path appended to Base URL for GraphQL requests.
Timeout (Seconds) 30 HTTP request timeout. Range 1–120.
Verify TLS Peer on Leave on for production. Disable only for self-signed labs.
Verify TLS Hostname on Leave on for production. Disable only for hostname mismatches in labs.
Import Source Tags off When on, Infrahub tags become canonical tags in rConfig and are attached on Apply.
GraphQL Root Field InfraDevice Top-level GraphQL field that contains the device edges. Change if your Infrahub schema names devices differently.
GraphQL Query provided (see below) The query rConfig sends. Must declare $offset: Int! and $limit: Int! and return { count, edges { node { ... } } }.

The default GraphQL query is:

query rConfigInfraDevice($offset: Int!, $limit: Int!) {
InfraDevice(offset: $offset, limit: $limit) {
count
edges {
node {
id
name {
value
}
primary_address {
node {
address {
value
}
}
}
platform {
node {
name {
value
}
}
}
device_type {
node {
name {
value
}
manufacturer {
node {
name {
value
}
}
}
}
}
tags {
edges {
node {
name {
value
}
}
}
}
}
}
}
}

Customise it to surface additional fields (location, role, custom attributes): but keep the count / edges { node { ... } } shape the driver expects.

Authentication

  • API Token (required). Generated under Account in Infrahub. Stored as a secret. The driver sends it as the X-INFRAHUB-KEY header.

Click Test Connection in the action bar. The driver POSTs a small introspection-style query to the configured GraphQL Path with X-INFRAHUB-KEY set.

Setup tab after a successful Test Connection (green status pill) (Zabbix example) Setup tab after a successful Test Connection (green status pill). Shown with the Zabbix driver. The Infrahub screen is the same.

Common failures:

What you see Most likely fix
Connection refused / timeout Wrong Base URL or firewall in between rConfig and Infrahub.
SSL / certificate error Self-signed cert: toggle Verify TLS Peer / Hostname off (lab only).
401 / 403 API token revoked, expired, or scoped to an account without GraphQL access.
200 with GraphQL errors array populated Configured root field doesn’t exist, or the query doesn’t compile against the schema.

Click Save. Move to Step 2 before running a preview.

The default Infrahub schema does not carry a profile-slug attribute, so the driver can’t read a profile from each device. Every Infrahub device takes the instance’s Default Device Profile (V8.4.3 and later).

2.1 Create the Device Profile and set it as the default

Section titled “2.1 Create the Device Profile and set it as the default”

Navigate to Inventory → Device Profiles → New Device Profile, fill in vendor, category, template, credential set, and save.

Inventory → Device Profiles list

Back on the Infrahub integration’s Setup tab, choose the profile under Default Device Profile and save. If the profile is later deleted, candidates are rejected as Device profile unusable until you choose another.

To give different device classes different profiles, run one Infrahub V2 instance per class, each with a GraphQL query scoped to that class and its own Default Device Profile.

2.2 Customise the GraphQL query (optional)

Section titled “2.2 Customise the GraphQL query (optional)”

The default query returns the most common Infrahub device fields. Common customisations:

  • Add a location { node { name { value } } } block to use Infrahub locations as additional rConfig tags.
  • Filter at query time by adding a GraphQL filter argument (e.g. InfraDevice(role__name__value: "router", offset: $offset, limit: $limit) { ... }): this is the Infrahub-native way to scope a sync.
  • Add custom attributes (my_custom_attribute { value }) so they appear in the Extract Preview row Details for diagnosis.

Click Extract Preview in the action bar (amber download icon).

Extract Preview tab with summary cards and result table (Zabbix example) Extract Preview tab with summary cards and result table. Shown with the Zabbix driver. The Infrahub screen is the same.

The driver issues the configured query with offset = 0 and the schema’s default page size, walks the result set page-by-page, and returns one row per edges[].node.

Open a row’s Details hover to see the full payload: confirm name.value, primary_address.node.address.value, device_type.node.name.value and any custom fields you added.

For the full anatomy of this tab, see the Extract Preview Tab reference.

Click Preview Sync in the action bar (sky icon). Sync Preview runs the complete pipeline through decide and stops without writing.

Switch to the Run Insights tab to inspect the result.

Run Insights tab populated after a Sync Preview (Zabbix example) Run Insights tab populated after a Sync Preview. Shown with the Zabbix driver. The Infrahub screen is the same.

For Infrahub the most-watched stage metrics are:

  • extract.items_extracted: should match the GraphQL count value.
  • canonicalize.invalid: non-zero usually means a node has no primary_address set, or name.value is empty.
  • reconcile.ambiguous: non-zero means more than one rConfig device matches the same Infrahub node.

If Open Problems is greater than zero, switch to the Problem Devices tab and triage the rows.

For the full anatomy of these tabs, see the Run Insights Tab reference and Problem Devices Tab reference.

When the Sync Preview decisions look correct and Open Problems is at an acceptable level, click Full Sync in the action bar (indigo icon).

Full Sync re-runs the full pipeline and finishes by executing the apply stage:

  1. Creates new devices for each decision = create, on the instance’s Default Device Profile.
  2. Updates existing devices for each decision = update.
  3. Syncs canonical tags onto the device when Import Source Tags was on at Setup.
  4. Updates integration_device_links (first_seen, last_seen).
  5. Schedules an initial configuration backup for newly created devices.

Run Insights tab after a Full Sync, with the apply stage card populated (Zabbix example) Run Insights tab after a Full Sync, with the apply stage card populated. Shown with the Zabbix driver. The Infrahub screen is the same.

Re-check Problem Devices after Apply.

For any of the runs above, you can swap the action-bar button for the Open Debug Console button (shimmer icon).

Debug Console modal mid-run (Zabbix example) Debug Console modal mid-run. Shown with the Zabbix driver. The Infrahub screen is the same.

Debug Console modal after a run completes (Zabbix example) Debug Console modal after a run completes. Shown with the Zabbix driver. The Infrahub screen is the same.

For the full anatomy of the dialog, see the Debug Console reference.

Once a manual Full Sync completes cleanly, navigate to Tasks and click New Task. Choose task type Integration V2 Job, pick the Infrahub instance, choose Apply mode, and set the cron schedule.

Terminal window
# Sync Preview (does not write)
php /var/www/html/rconfig8/current/artisan rconfig:integration-v2-run --driver=infrahub --mode=preview
# Full Sync (Apply) by explicit instance ID, with debug output
php artisan rconfig:integration-v2-run 24 --mode=apply --debug
# Queue an async run
php artisan rconfig:integration-v2-run 24 --mode=apply --queue
Canonical field Infrahub payload paths checked, in order
External ID id
Hostname name.value
Primary IP primary_address.node.address.value
Serial not populated by default schema
Vendor device_type.node.manufacturer.node.name.value
Model device_type.node.name.value
Tags tags.edges[*].node.name.value
Profile slug not populated: the instance’s Default Device Profile is used (see Step 2)
  • Strong match: by instance_link_external_id (Infrahub id) only.
  • Medium match: hostname and primary IP both unique in rConfig.
  • No automatic medium-match auto-relink, no cross-family matching.

The default mode is disable_link_only: when a previously-synced Infrahub node disappears from the GraphQL result set, rConfig disables the integration_device_links row but leaves the device intact.

  • Test connection passes but Extract returns zero devices. Run the configured GraphQL Query directly against Infrahub via a GraphQL client to confirm the query itself returns rows. The Test Connection only proves auth and schema-compatibility, not a populated result set.
  • GraphQL errors array populated in stage output. The query failed to compile or the configured Root Field doesn’t exist. Confirm the field name matches your Infrahub schema (it is case-sensitive).
  • Canonicalize flags many candidates as invalid. Most common: primary_address not assigned in Infrahub, or your customised query forgot to include the address path.
  • Every candidate lands in Problem Devices as missing_required_tag. No Default Device Profile is set on the Setup tab. Set one and run again.
  • Reconciliation produces ambiguous matches. Two rConfig devices share the same hostname or primary IP. Resolve in Problem Devices by picking the correct target.
  • Slow runs / very large extracts. Tighten the GraphQL query with filter arguments to reduce the result set, or increase timeout_seconds if the GraphQL response itself is slow.

Using a source of truth to drive rConfig’s inventory, and bringing it to an rConfig that already has devices, is explained in the Integrations guides:

Uplink guideSource of truth first: NetBox, Nautobot and InfrahubDrive rConfig's inventory from NetBox, Nautobot or Infrahub: what the pattern gives you, how profiles and filters work, and where it needs care.Read the guide