Infrahub Device Sync V2

Infrahub Device Sync V2: 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

Interactive demo

Mental Model: End Goal First

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:

Create the integration instance — Infrahub connectivity, GraphQL query and auth in the Setup tab. Validate with Test Connection.
Set up a default Device Profile the synced devices will inherit from. Infrahub does not surface per-device profile metadata in the default schema, so you must rely on the instance default.
Run an Extract Preview to confirm your GraphQL query returns the right Infrahub devices.
Run a Sync Preview to walk the full pipeline (canonicalize → reconcile → decide) without writing.
Run a Full Sync (Apply) once the preview’s decisions look right.
Schedule the integration to run on a cron from the rConfig scheduler.

Prerequisites

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
A clear answer to: which Device Profile every Infrahub-extracted device should adopt by default. The default Infrahub schema does not surface a profile-slug attribute, so a default profile on the integration instance is effectively required.

Step 1 — Create the Integration Instance (Setup Tab)

1.1 Open the V2 driver picker

Navigate to Settings → Integrations, then click New V2 Integration.

Placeholder — V2 driver picker (Settings → Integrations → New V2 Integration) with Infrahub highlighted

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

1.2 Fill in the schema-driven Setup tab

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

Placeholder — 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.

1.3 Test the connection

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.

Placeholder — Setup tab after a successful Test Connection (green status pill)

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.

1.4 Save

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

Step 2 — Set Up the Default Device Profile (Inventory)

The default Infrahub schema does not carry a profile-slug attribute — device_profile.supported = false in infrahub.schema.php. In practice this means:

Pick one rConfig Device Profile to use as the default for every Infrahub-extracted device.
Set that profile as the default profile on the integration instance.
If you need different profiles for different device classes, either run one Infrahub V2 instance per class (each with a scoped GraphQL query and its own default profile), or extend the default GraphQL query to surface a custom attribute and post-process upstream.

2.1 Create the default Device Profile

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

Placeholder — Inventory → Device Profiles list

2.2 Pin the default profile on the instance

Back on the Infrahub integration Detail page, switch to the Policies view and set the Default Device Profile to the slug you just created.

Placeholder — Infrahub instance Policies view with the default Device Profile selected

2.3 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.

Step 3 — Run an Extract Preview

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

Placeholder — Infrahub Extract Preview tab with summary cards and result table

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.

Step 4 — Run a Sync Preview

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.

Placeholder — Run Insights tab populated after an Infrahub Sync Preview

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.

Step 5 — Run a Full Sync (Apply)

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:

Creates new devices for each decision = create, attached to the instance default Device Profile.
Updates existing devices for each decision = update.
Syncs canonical tags onto the device when Import Source Tags was on at Setup.
Updates integration_device_links (first_seen, last_seen).
Schedules an initial configuration backup for newly created devices.

Placeholder — Run Insights tab after a Full Sync, with the apply stage card populated

Re-check Problem Devices after Apply.

Step 6 — The Debug Console

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

Placeholder — Debug Console modal mid-run for the Infrahub driver

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

Step 7 — Schedule the Sync

Once a manual Full Sync completes cleanly, navigate to Scheduled Tasks → Add Task → Integration V2 Job, pick the Infrahub instance, choose Apply mode, and set the cron schedule.

CLI Reference

# 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

Driver Reference

Infrahub fields the driver reads

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 — relies on instance default Device Profile

Reconciliation policy

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.

Missing upstream policy

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.

Troubleshooting

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.
Profile resolution always falls back to default. This is expected — the default Infrahub schema does not expose a profile-slug attribute. Either accept the default-profile model, or split into multiple instances scoped by query.
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.

Device Sync V2 Overview
Statseeker Device Sync V2 — the model V2 setup
Extract Preview Tab
Run Insights Tab
Problem Devices Tab
Logs Tab
Debug Console
Checkmk Device Sync V2
Scheduled Tasks