New Netbox to Infrahub data sync tutorial#140
Conversation
Adds a tutorial for syncing public NetBox demo data into a local Infrahub instance and exposes it in the docs sidebar.
Validation:
- uv run pytest -q
- npx markdownlint-cli2 "docs/docs/**/*.{md,mdx}"
- uv run invoke docs.docusaurus
Generated with Codex.
Refreshes the tutorial after local validation: pins commands to the published 2.0.0 package, documents demo token and startup behavior, aligns verification with current public NetBox data, and keeps the order guidance focused on auto-derived write ordering. Also fixes the NetBox example config serial_number Transformation expression by removing a stray trailing brace and corrects the dmi01 comment so reviewers can inspect that config change directly. Generated with Codex.
|
Warning Review limit reached
Next review available in: 47 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis PR adds a new tutorial documenting how to sync NetBox demo data into Infrahub, registers it in the docs sidebar, and adds a spelling exception term. It also substantially rewrites the example netbox_to_infrahub config.yml: removing hard-coded credentials, updating usage comments for auto-tiered write order and parquet caching, and replacing schema mappings for locations, racks, manufacturers, devices, interfaces, circuits, and IPAM objects to align with an updated Infrahub schema. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying infrahub-sync with
|
| Latest commit: |
0205d12
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://8154652a.infrahub-sync.pages.dev |
| Branch Preview URL: | https://feature-netbox-demo-tutorial.infrahub-sync.pages.dev |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/docs/tutorials/netbox-demo-to-infrahub.mdx`:
- Around line 118-139: Pin the schema download in the tutorial setup to an
immutable reference instead of the mutable BRANCH value. Update the schema fetch
logic around BASE_URL and FILES so it targets a specific commit hash or release
tag, matching the reproducibility approach already used elsewhere in the
tutorial, and keep the download paths unchanged.
- Line 191: The tutorial link is still pinned to an older infrahub-sync commit,
so it downloads the wrong config file. Update the raw GitHub URL in the
netbox-demo-to-infrahub tutorial to point at the commit that contains the
rewritten netbox-demo-to-infrahub config.yml, using the existing tutorial link
text and the config reference as the identifiers to locate it.
In `@examples/netbox_to_infrahub/config.yml`:
- Around line 39-43: The example config is missing the required order key, even
though it should still preserve auto-tiering. Update the config example to
include the order field as part of the expected YAML keys in this sample, and
keep it empty so infrahub-sync continues to compute tiers from schema_mapping.
Use the existing example block in config.yml and remove the stale commented
CoreStandardGroup order example so the sample matches the documented structure.
- Around line 369-374: The `InterfaceVirtual` and `InterfaceLag` VLAN mappings
are using `reference: IpamVLAN`, which can resolve to missing nodes when VLANs
have no group and break sync. Update the `untagged_vlan` and `tagged_vlan`
entries in this config so they stay commented out like `InterfacePhysical`, and
only re-enable them once skipped VLAN handling is supported.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 277dc30f-b521-4436-8a0b-99d362549e14
📒 Files selected for processing (4)
.vale/styles/spelling-exceptions.txtdocs/docs/tutorials/netbox-demo-to-infrahub.mdxdocs/sidebars.tsexamples/netbox_to_infrahub/config.yml
lancamat1
left a comment
lancamat1
left a comment
There was a problem hiding this comment.
I went through this tutorial end to end as a new user (fresh copier project, local Infrahub via Docker, live public NetBox demo), running every command verbatim and doing the UI steps in a browser. A lot is solid — the NetBox token warnings match the real 4.6 nbt_/Bearer/Key traps exactly, the bottom-left login and seeded admin token are accurate, and generate/diff behave as described.
The headline: the sync doesn't complete out of the box. LocationSite requires a mandatory parent the config never maps, so sites — and everything under them — fail to import and sync exits 1; the tutorial's own verification commands then return nothing. Details + a tested analysis inline (the main comment is on config.yml). Also: the pinned config commit is stale, the copier "press Y" instruction breaks the project, a Troubleshooting entry for the demo's duplicate-object error, and a best-practice suggestion to sync into a branch + Proposed Change.
(Supersedes my earlier retracted review — apologies for that noise.)
| # Netbox "region" model is relatively loose and could accommodate multiple layers of nested objects (e.g. continent > country > city). | ||
| # In Infrahub you have to explicitly define this hierarchy in the schema. | ||
| # As every organization organizes this differently, we don't provide out-of-the-box support for it, even though we provide a couple of examples in the schema library / marketplace. | ||
| # For the sake of having a first working sync, we've defined a very basic site node in the schema that you can build upon once your hierarchy is clear. |
There was a problem hiding this comment.
This is the single thing that stops the tutorial from completing. The comment promises a "first working sync" from a basic site node with hierarchy added later — but that isn't what happens.
The location_minimal schema this tutorial loads defines Site with a mandatory parent: LocationCountry (Region→Country→Site). With this config — which maps only dcim.sites and leaves the region/country blocks below commented out — sync exits 1:
GraphQLError: 'parent is mandatory for LocationSite at parent'
{'code': 'ATTRIBUTE_REQUIRED', 'http_status': 422, 'node_kind': 'LocationSite'}
Because sites are tier 1, nothing below them imports either (racks, devices, interfaces, prefixes, IPs, circuits), so the tutorial's own verification commands both come back empty:
$ uv run infrahubctl object get LocationSite --limit 5 -> No objects of kind LocationSite found.
$ uv run infrahubctl object get IpamPrefix --limit 5 -> No objects of kind IpamPrefix found.
which, per the tutorial's "if these commands return objects, the sync imported data successfully" line, reads as total failure.
I also tested the obvious next step — uncommenting the LocationRegion/LocationCountry blocks below. That fails even earlier, at NetBox load:
ERROR loading Netbox: 1 validation error for LocationCountry - parent Field required
because the demo's dcim.regions don't fit the assumed depth-0/depth-1 model, and LocationSite still maps no parent. So it genuinely does not work out of the box.
Fix options: ship a schema where Site.parent is optional / top-level (matching this comment's promise), or extend the config to build the region→country→site parentage and map LocationSite.parent. As-is a new user cannot finish the tutorial.
There was a problem hiding this comment.
Argh, I did this schema extensions/location_site/location_site.yml for the sync but forgot to reflect it in the tutorial 😬 that should replace the location minimal and issues coming with it
| After reviewing the diff, run the sync. | ||
|
|
||
| ```bash | ||
| uv run infrahub-sync sync --name netbox-demo-to-infrahub --directory sync-projects --diff |
There was a problem hiding this comment.
Enhancement / best practice: consider syncing into a new Infrahub branch here rather than main, then creating a Proposed Change in the UI to review and merge it.
Branching + Proposed Change review is one of Infrahub's core differentiators and the recommended (best-practice) way to land data changes — syncing straight to main skips the very workflow a getting-started guide is best placed to showcase. infrahub-sync supports it directly: --branch <name> on diff/sync (or a branch: key under destination settings). Note the branch must exist first (infrahubctl branch create <name>), since sync won't create it. It turns the final step into a natural lead-in to "now review and merge your change."
Co-authored-by: lancamat1 <135596273+lancamat1@users.noreply.github.com>
Co-authored-by: lancamat1 <135596273+lancamat1@users.noreply.github.com>
Co-authored-by: lancamat1 <135596273+lancamat1@users.noreply.github.com>
3 participants
Summary by CodeRabbit
New Features
Chores
RIRsto support documentation checks.docs/docs/tutorials/netbox-demo-to-infrahub.mdx) that walks a reader from zero — no existing Infrahub instance required — through scaffolding a project, starting Infrahub, installing Infrahub Sync, loading a schema, and running a first NetBox → Infrahub sync against the public NetBox demo. Readers who already have Infrahub running are pointed straight to the NetBox adapter docs instead.examples/netbox_to_infrahub/config.yml) to target the production-grade schema-library schema instead of the ad-hoc example schema used previously, covering DCIM, IPAM, and organization objects with the same core domains as NetBox.docs/sidebars.ts.What's covered
Sites, racks, devices and interfaces, VRFs/VLANs, prefixes/IP addresses, circuits, tags, and organizations (manufacturers, providers, RIRs).
Known limitations / follow-ups
TODOs inconfig.yml.curlloop and the pinned-commit config download are stand-ins until schema distribution moves through the marketplace and config distribution firms up.