NetBox Device Types Conversion
Relevant source files
The following files were used as context for generating this wiki page:
- skills/infrahub-converting-netbox-device-types/SKILL.md
- skills/infrahub-converting-netbox-device-types/concepts.md
- skills/infrahub-converting-netbox-device-types/reference.md
- skills/infrahub-converting-netbox-device-types/rules/coverage-report-unmapped.md
- skills/infrahub-converting-netbox-device-types/rules/mapping-profile-driven.md
- skills/infrahub-converting-netbox-device-types/rules/workflow-schema-prerequisites.md
NetBox Device Types Conversion transforms static YAML definitions from the NetBox community library into Infrahub object templates. The system uses a Python converter and mapping profiles to turn vendor hardware definitions into reusable blueprints that pre-configure device ports and components.
Sources: SKILL.md:15-20, concepts.md:6-10
Architecture and Data Flow
The conversion process splits a single NetBox input file into three distinct Infrahub artifacts. This separation distinguishes hardware facts (such as weight and height) from structural blueprints (such as interface lists).
The diagram shows how the converter processes NetBox YAML using a mapping profile to generate sequenced Infrahub YAML files and a coverage report.
Transformation Split
The converter maps NetBox data according to the following logic:
| NetBox Component | Infrahub Artifact | Purpose |
|---|---|---|
manufacturer | OrganizationManufacturer | First-class object for vendors |
model, u_height, weight | DcimDeviceType | Static hardware model facts |
interfaces, console-ports | TemplateDcimDevice | Reusable structural blueprint |
Sources: SKILL.md:66-73, concepts.md:37-43
Mapping Profiles
Mapping profiles drive the conversion by binding NetBox fields to specific Infrahub attributes. The converter does not guess names; every destination kind and attribute must be defined in the profile.
Core Configuration Keys
Profiles require specific keys to map the complex relationship between devices and templates:
device_type: Defines the Infrahub kind and fields for physical hardware data.template: Defines theTemplate<Kind>and the relationship link back to theDcimDeviceType.components: Maps NetBox component lists (e.g.,interfaces) to concrete Infrahub template kinds.
Sources: reference.md:126-155, rules/mapping-profile-driven.md:13-18
Value Coercion and Transforms
The converter applies specific transforms to NetBox values during processing:
number: Coerces values to integers, rounding half-away-from-zero (e.g., 0.5 becomes 1).boolean: Coerces values to true/false.weight_kg: Converts NetBox weight values into whole kilograms based on the provided unit.
Sources: reference.md:159-175
Schema Prerequisites
Infrahub only allows loading converted templates if the target schema is configured to support them.
Template Generation Flag
A node must declare generate_template: true for the Template<Kind> to exist. Setting this property on a generic has no effect; it must reside on the concrete node definition.
The diagram illustrates the generation relationship between a schema node and its resulting template structures.
Component Relationships
Infrahub generates component templates only for relationships defined with kind: Component. Relationships defined as kind: Attribute point to independent objects (like a Location) and do not result in templated children.
Sources: rules/workflow-schema-prerequisites.md:13-25, concepts.md:88-100
Conversion Workflow
Converting NetBox device types involves specific CLI operations and sequenced loading to respect object dependencies.
Execution Procedure
- Clone Library: Perform a sparse checkout of the
netbox-community/devicetype-libraryto obtain YAML files. - Run Converter: Execute the Python script providing the input directory, mapping profile, and output directory.
- Audit Report: Review the
coverage-report.mdfor any skipped component lists or dropped fields. - Sequence Load: Load files onto an Infrahub branch in numeric order (01 through 05).
Sources: SKILL.md:112-117, SKILL.md:129-136, reference.md:195-201
Coverage Reporting
The converter generates a report identifying data loss. This occurs when the NetBox file contains data that has no corresponding definition in the Infrahub mapping profile or target schema.
| Category | Example |
|---|---|
| Skipped Lists | console-ports (if no component relationship exists) |
| Dropped Fields | airflow (if no attribute exists on the target node) |
| Shadowed Values | comments (if description was chosen as the primary source) |
Sources: rules/coverage-report-unmapped.md:27-35, reference.md:108-115
Module Type Conversion
Module types (line cards, transceivers) follow a similar conversion path but lack a slug. The converter uses the model field as the identity key.
The {module} Token
Most component names in NetBox module types contain a {module} placeholder. Because the bay position is unknown until installation, Infrahub imports these as declarations. A separate generator resolves the {module} token into real device interfaces after the module is installed in a bay.
Sources: SKILL.md:80-87, reference.md:46-55
Summary
NetBox Device Types Conversion automates the population of Infrahub hardware libraries. By splitting data into manufacturers, device types, and structural templates, the system enables rapid device instantiation while maintaining data integrity. Successful conversion requires a schema configured for template generation and a mapping profile that accurately reflects the Infrahub data model.
Sources: SKILL.md:38-42, concepts.md:6-13