Nautobot Device Sync V2

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

The V2 Nautobot driver pulls device inventory from a Nautobot server using its REST API and feeds it 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.

Marketing overview on rconfig.com

See the Nautobot integration page on rconfig.com for the platform-specific overview, or browse all rConfig integrations.

Platform	rConfig V8 Support	Auth supported	V2 Status
Nautobot	V8.2.0+	API token	Field tested

Field tested in customer environments

The Nautobot V2 driver is field tested in live customer environments for the V8.2.0 release. The schema declares this status in nautobot.schema.php → verified.status. Please report any issues to rConfig support.

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 Nautobot 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 Nautobot 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 — Nautobot connectivity and auth in the Setup tab. Validate with Test Connection.
2. Set up the Device Profiles the synced devices will inherit from. This happens under Inventory → Device Profiles, not in the integration itself.
3. Run an Extract Preview to confirm filters return the right Nautobot 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.

Prerequisites

Nautobot:

• A reachable Nautobot server with the REST API enabled
• An API token for a service user with read access to /dcim/devices/, /extras/tags/ and /ipam/ip-addresses/
• Network connectivity from rConfig to Nautobot
• A custom field of type Text named rconfig_device_profile added to the dcim | device content type — this is the field the V2 driver reads to resolve the Device Profile slug
• Optional: tags and sites for upstream filtering

rConfig V8.2.0+:

• Administrator access
• A clear answer to: which Device Profile (vendor, category, template, credential set, optional SNMP group / Vector agent) every synced device should adopt by default

Step 1 — Create the Integration Instance (Setup Tab)

1.1 Open the V2 driver picker

Navigate to Settings → Integrations, then click New V2 Integration. The driver picker shows every V2 driver in two groups: drivers you’ve already configured and drivers you haven’t.

Each card carries the driver’s verification badge — Field tested for Nautobot — plus a link to its docs page. Click the Nautobot card.

1.2 Fill in the schema-driven Setup tab

The driver picker drops you straight into the instance Detail page on the Setup tab. The form is rendered from nautobot.schema.php and is laid out in two sections.

Connectivity

Field	Default	Notes
Base URL	required	Root of the Nautobot server, e.g. https://nautobot.example.com. No trailing slash needed.
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, Nautobot tag slugs become canonical tags in rConfig and are attached on Apply.

Authentication

• API Token (required). Generated under Admin → Users → Tokens in Nautobot. Stored as a secret. The driver sends it as Authorization: Token <api_token>.

1.3 Test the connection

Click Test Connection in the action bar at the top of the page.

The driver hits GET /dcim/devices/?limit=1. Common failures:

What you see	Most likely fix
Connection refused / timeout	Wrong Base URL or firewall in between rConfig and Nautobot.
SSL / certificate error	Self-signed cert — toggle Verify TLS Peer / Hostname off (lab only).
401 / 403	Token revoked, expired, or scoped to a user without dcim.view_device permission.
404	API not reachable at the expected path — check Nautobot reverse proxy / sub-path config.

1.4 Save

Click Save. The runtime config is written to integration_instances.runtime_config and the auth material is stored via secrets_ref. The save indicator in the action bar flips to Saved once persisted.

Step 2 — Set Up Device Profiles (Inventory)

Device Profiles live outside the integration. They are the rConfig-side definition of what a synced device should look like — vendor, category, device template, credential set, optional SNMP group and Vector agent. Each profile has a slug; the V2 driver matches the upstream record’s custom_fields.rconfig_device_profile value to that slug to pick the profile.

2.1 Open the Device Profiles page

Navigate to Inventory → Device Profiles.

2.2 Create a Device Profile per device class

For each device class you want to sync (e.g. Cisco IOS Core Routers, Arista Edge Switches), click New Device Profile and fill in:

• Name — human-readable.
• Slug — the value Nautobot’s rconfig_device_profile custom field will reference.
• Vendor, Category, Template, Credential set — standard rConfig device classification.
• SNMP group, Vector agent, default tags, default model / prompt patterns — optional.

2.3 Populate the custom field on the Nautobot side

The Nautobot V2 driver reads the profile slug only from custom_fields.rconfig_device_profile (nautobot.schema.php → device_profile.source_profile_paths). Tags and groups are not used for profile resolution in this driver — the custom field is authoritative.

In Nautobot:

1. Navigate to Extensibility → Custom Fields → + Add.
2. Content types: dcim | device.
3. Type: Text.
4. Name: rconfig_device_profile (must match exactly).
5. Save.
6. Open each device, set the rconfig_device_profile custom field to the matching rConfig Device Profile slug (e.g. cisco-ios-core).

If you cannot tag every device immediately, set a default profile on the Nautobot integration instance so untagged devices inherit a sensible fallback.

Step 3 — Run an Extract Preview

Return to Settings → Integrations → V2 → Nautobot and click Extract Preview in the action bar (amber download icon).

Extract Preview hits Nautobot exactly the way a real sync would, but stops the moment the records come back — no canonicalize, no reconcile, no writes.

Nautobot supports filters on:

• tag (operators: equals, in, contains_all, contains_any)
• site (operators: equals, in)
• status (operators: equals, in)

Open a row’s Details hover to see the full raw payload — confirm name, the chosen IP field (primary_ip4.address or primary_ip.address) and the custom_fields.rconfig_device_profile value used for profile resolution are all present.

On-the-fly hydration

The Nautobot driver hydrates tag and IP-address references when the upstream returns IDs instead of inline objects (calls to /extras/tags/{id}/ and /ipam/ip-addresses/{id}/). Hydration adds extra round-trips for large inventories — give the run a little more wall-clock budget than you would for NetBox.

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.

For Nautobot the most-watched stage metrics are:

• extract.items_extracted — should match the Extract Preview count (within filter scope).
• canonicalize.invalid — non-zero usually means a device has no primary_ip4/primary_ip set, or the rconfig_device_profile custom field is empty / doesn’t resolve.
• reconcile.ambiguous — non-zero means more than one rConfig device matches the same Nautobot device.

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:

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

Re-check Problem Devices after Apply — Apply does not auto-resolve ambiguous_match or conflict rows; those still need a human.

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). The Debug Console runs the same Artisan command synchronously and streams its native stdout/stderr into a modal:

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

Step 7 — Schedule the Sync

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

A common production pattern:

• Hourly Preview — drift detection only, no writes.
• Nightly Apply — commits real changes during the maintenance window.

CLI Reference

# Sync Preview (does not write)
php /var/www/html/rconfig8/current/artisan rconfig:integration-v2-run --driver=nautobot --mode=preview

# Full Sync (Apply) by explicit instance ID, with debug output
php artisan rconfig:integration-v2-run 14 --mode=apply --debug

# Queue an async run
php artisan rconfig:integration-v2-run 14 --mode=apply --queue

Driver Reference

Nautobot fields the driver reads

Canonical field	Nautobot payload paths checked, in order
External ID	id
Hostname	name
Primary IP	primary_ip4.address → primary_ip.address
Serial	serial
Vendor	device_type.manufacturer.name
Model	device_type.model
Tags	tags[*].slug
Profile slug	custom_fields.rconfig_device_profile (only path)

If the upstream returns tag IDs instead of objects, the driver fetches each tag via /extras/tags/{id}/. Same for IP addresses via /ipam/ip-addresses/{id}/.

Reconciliation policy

• Strong match — by instance_link_external_id (Nautobot id).
• 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 Nautobot device disappears from the upstream, rConfig disables the integration_device_links row but leaves the device intact.

Troubleshooting

• Connection works, credentials fail. Confirm the API token is active in Nautobot and the owning user has dcim.view_device permission. Tokens scoped to a single object permission group can pass /dcim/devices/?limit=1 but fail when reading tags or IPs — give the user broad read access.
• Extract returns zero devices. Re-check tag / site / status filters and the API user’s object permissions. Nautobot will silently filter records the user cannot see.
• Canonicalize flags candidates as invalid. Most common: primary_ip4 not assigned on the device, or custom_fields.rconfig_device_profile empty / pointing at a Device Profile that doesn’t exist.
• Profile resolution fails. Confirm the custom field is named exactly rconfig_device_profile (lowercase, underscore), is attached to the dcim | device content type, and its value matches an active rConfig Device Profile slug.
• Reconciliation produces ambiguous matches. Two rConfig devices share the same hostname or primary IP. Resolve in Problem Devices by picking the correct target, or de-duplicate the device list.
• Slow runs. Hydration of tag and IP IDs is the usual cause. Ensure your Nautobot API serializer is returning inline objects where possible, or accept the extra wall-clock for large inventories.

Related Documentation

• 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
• NetBox Device Sync V2
• Scheduled Tasks