If your team maintains a device type catalog in NetBox, you’ve probably invested considerable effort in it. Every switch, router, and line card has a definition that captures its physical characteristics and components, often down to individual interfaces and ports.
You shouldn’t have to recreate that work when adopting Infrahub.
The NetBox Device Type Converter, an Infrahub Skill, lets you reuse device and module type definitions from your NetBox instance or the community-maintained NetBox Device Type Library.
The Skill converts those definitions into Infrahub objects and reusable Object Templates, taking your target data model into account. You get a starting point for building devices in Infrahub without manually defining every port on a 48-port switch.
The challenge is handling the differences between NetBox’s data model and the schema you’ve chosen for Infrahub.
Why importing NetBox device types is harder than it sounds
NetBox and Infrahub represent infrastructure data differently so a fixed import script won’t work.
NetBox uses a predefined data model. A device type has fields such as model, u_height, and part_number, along with lists of components such as interfaces, console ports, and power ports.
Infrahub lets you define your own schema. Your device type might have an attribute named height instead of u_height. Console ports might be represented as a separate object type, modeled through a shared interface relationship or excluded entirely.
Those differences make a universal field-for-field importer impractical.
Consider a NetBox device type with 48 interfaces, two power ports, and one console port. The interface definitions might map cleanly to your Infrahub schema while the console port has no equivalent destination.
A conversion script that assumes every Infrahub schema looks the same could generate invalid data, omit components, or map them incorrectly.
The NetBox Device Type Converter Skill addresses these challenges by separating the mechanics of conversion from decisions about how the source and target data models relate.
How the Infrahub Skill converts NetBox device types
The infrahub-converting-netbox-device-types Skill works with an AI coding assistant and a set of bundled Python scripts.
You can start with YAML files from the NetBox community library or export definitions from a running NetBox instance. The export script produces the same format used by the library, so both sources follow the same conversion process.
The skill then uses a YAML mapping profile to connect NetBox fields and components to the corresponding kinds, attributes, and relationships in your Infrahub schema.
For a custom schema, the AI assistant can help inspect the model and build that profile. The Python scripts then perform the conversion, rather than relying on the AI to generate hundreds of component definitions individually.
That division of work is critically important.
An AI assistant can help interpret how your schema represents a console port. Once that mapping is established, a script is better suited to generating the same structure consistently across thousands of device definitions.
The converter produces several types of Infrahub objects:
- Manufacturers: Separate manufacturer objects.
- Device types: Model information such as part numbers, height, and weight.
- Device Templates: Reusable device structures with their component nested Templates.
- Module types: Definitions for supported modules and, where configured, their components.
The generated YAML files are numbered in dependency order so manufacturers can be loaded before device types and Templates that reference them. The result is a set of files you can inspect and load into Infrahub.
What makes the conversion reliable
When you’re converting a large catalog, successful script execution tells you very little about whether the output is complete.
A converter might process every file without raising an error while silently losing components along the way.
We encountered exactly that problem during development of the Skill. A relationship-handling bug reduced 108 expected component Templates to just four. The conversion completed and the reporting flagged no discrepancy.
The problem arose because multiple NetBox component lists could map to the same Infrahub relationship. Instead of accumulating the components, the converter was overwriting earlier entries.
The scripts now account for shared relationships, preserving components from each source list.
Other safeguards address equally subtle problems:
- Mappings are explicit. The converter reads destination names from the mapping profile. It doesn’t invent an Infrahub attribute or relationship when one hasn’t been defined.
- Field conflicts are handled deliberately. If two NetBox fields could map to the same destination, the profile must define which takes precedence. An undeclared conflict is rejected rather than resolved arbitrarily.
- Unsupported data is reported. Each conversion generates a Markdown coverage report identifying fields and components that couldn’t be mapped.
The coverage report gives you a practical list of what to review before importing the data.
For example, the bundled schema-library.yml mapping profile doesn’t cover every component list available in NetBox. Seeing unmapped components in the report is expected. You can decide whether to extend your Infrahub schema, adjust the mapping, or accept the omission.
A clean run and a complete conversion are two different things. The report helps you tell them apart.
How the Skill handles Infrahub’s flexible data model
Infrahub’s schema flexibility lets you build an infrastructure data model around your automation requirements. It also means the converter has to respect the model you’ve defined.
Three Infrahub capabilities are particularly relevant.
Infrahub Object Templates capture reusable device structures
Infrahub separates device model information from the structure used to create a device.
A device type stores characteristics such as its manufacturer, model, height, and part number. An Object Template defines the reusable structure, including components such as interfaces. Device Templates and Module Templates are simply Object Templates for those specific kinds of objects.
You can use a Device Template to create devices without defining their component structure from scratch each time.
The schema must explicitly enable Template generation through generate_template: true. The converter checks for that setting because Template kinds don’t automatically exist for every node.
If the schema needs changes, the Skill can propose them for review. It doesn’t apply those changes without your involvement.
Generics can accommodate different component models
Suppose your NetBox catalog distinguishes between Ethernet interfaces and console ports, but your Infrahub schema represents both through a common interface relationship.
Infrahub’s generic types can provide that shared relationship while allowing more specific interface types underneath it.
Depending on your schema, this can let you preserve different interface categories without introducing a separate relationship for every NetBox component type.
The mapping still has to describe the intended behavior. If your schema has no suitable console interface kind, for example, the converter will suggest a schema for you.
Generators handle module-dependent interface names
Modules introduce another complication.
A NetBox module definition may contain an interface named Ethernet{module}/1. The {module} placeholder represents the module’s eventual position in a device. That position isn’t known when you’re converting the module type.
With the required module schema extensions, module-port mapping profile, and a Template-enabled module schema, the Skill supports a workflow where module Templates retain port declarations. A bundled Infrahub Generator then resolves the placeholder when the module is installed and creates the corresponding device interfaces.
This preserves the distinction between a reusable module definition and the actual interfaces on an installed device.
How to import your NetBox device types
You can use the converter through most AI coding assistants. The Skill documentation also provides commands for running the bundled scripts manually.
Here’s a practical workflow.
1. Install the Infrahub Skills
Install the Skills collection using:
npx skills add opsmill/infrahub-skills
The collection includes the NetBox Device Type Converter Skill alongside other Infrahub Skills.
2. Check your target schema
Before converting anything, make sure your Infrahub schema supports the objects and Templates you want to create. In particular, confirm that the relevant nodes have generate_template: true enabled.
The Skill includes the ability to identify if there’s gaps in your existing schema, and can suggest schema changes drawn from the Infrahub Marketplace, including options for module types and module ports. It also provides a template for building a mapping profile against a custom schema.
If your schema differs from the supplied profiles, ask your AI assistant to help build a mapping that reflects your actual kinds, attributes, and relationships.
3. Choose which device types to convert
You can use definitions from the community library or export them from your own NetBox instance.
For example, you might ask your assistant:
Pull the device types we currently use from our NetBox instance, including module types, and convert them into Infrahub object templates.
The NetBox export script supports filtering to device and module types that are actually in use. You can also narrow the selection by manufacturer.
For a first conversion, selecting a few representative devices is a useful way to validate your mapping before processing a larger catalog.
If you’re exporting from a running NetBox instance, you’ll need a read-only API token and the Python dependencies specified in the documentation.
4. Review the generated files and coverage report
The converter writes separate YAML files for manufacturers, device types, device Templates, and any included module definitions.
Before loading them, review the coverage report.
Pay particular attention to unmapped component types, attributes that have no destination, and fields where the mapping applies precedence rules.
If something important is missing, you can update the mapping profile or make an approved change to your Infrahub schema and run the conversion again.
Because the scripts use explicit mappings, you can repeat the conversion with predictable results.
5. Load and validate the data in Infrahub
Use an Infrahub branch to test the generated data before merging it into your main dataset.
Load the files in their numbered dependency order, then create a test device from one of the imported Templates.
Check that the device has the expected components. A 48-port switch is a useful test case because missing interfaces are easy to spot. For modular devices, also validate how module Templates and interface generation behave.
Once you’re satisfied with the results, you can use Infrahub’s Proposed Change workflow to review and merge the imported data.
If you find problems, you can correct them on the branch without affecting your main dataset.
Reuse your device catalog without rebuilding it
Moving to a different infrastructure data model shouldn’t mean manually recreating the device definitions your team already maintains.
The NetBox Device Type Converter Skill provides a way to carry that work into Infrahub while accounting for differences in the underlying schemas.
Its combination of explicit mappings, repeatable conversion scripts, and coverage reporting makes it practical to start with a small set of devices, validate the results, and expand the import as needed.
Keep in mind that the converter creates a one-way snapshot of device definitions. It doesn’t continuously synchronize a live NetBox instance with Infrahub. Continuous synchronization requires a separate integration.
To get started, see the documentation on the NetBox Device Type Converter Skill, or explore the Infrahub Skills GitHub repository. You can also use the repo to report issues or suggest improvements to the conversion workflow.
