Inventory Data Model

Relevant source files

The following files were used as context for generating this wiki page:

• dev/knowledge/inventory-data-model.md
• AGENTS.md
• nornir_infrahub/plugins/inventory/infrahub.py
• dev/knowledge/architecture.md
• dev/knowledge/infrahub-sdk-integration.md
• pyproject.toml

The Inventory Data Model defines how data from Infrahub nodes maps to Nornir hosts and groups. The nornir-infrahub plugin acts as a bridge, resolving Infrahub attributes and relationships into standard Nornir inventory elements.

The model relies on a configurable mapping system that validates relationship depths and enforces a contract between the inventory and downstream task plugins. It uses Pydantic for configuration validation and the Infrahub SDK for synchronous data retrieval and schema inspection.

Sources: dev/knowledge/architecture.md, AGENTS.md, nornir_infrahub/plugins/inventory/infrahub.py:18-27

Core Configuration Models

The inventory plugin uses two primary data structures to define the source of Nornir hosts and the property mapping rules.

SchemaMappingNode

This Pydantic @dataclass captures individual mapping rules. It maps a Nornir host property (name) to a dotted path within the Infrahub node (mapping).
Sources: dev/knowledge/inventory-data-model.md, nornir_infrahub/plugins/inventory/infrahub.py:93-96

HostNode

This model defines which Infrahub nodes become Nornir hosts. It includes query filters and relationship pre-fetching instructions.

Field	Type	Description
kind	str	The Infrahub node kind (e.g., InfraDevice) to map to Nornir hosts.
include	List[str]	Relationships to pre-fetch. Always includes member_of_groups.
exclude	List[str]	Relationships to skip during the query.
filters	Dict[str, Any]	Query filters passed directly to the Infrahub SDK.

Sources: nornir_infrahub/plugins/inventory/infrahub.py:100-116, dev/knowledge/inventory-data-model.md

Mapping Resolution Logic

The resolution algorithm, implemented in resolve_node_mapping, translates dotted string paths into actual node values. The system enforces a strict relationship hop limit defined by MAX_RELATIONSHIP_HOPS = 2. This allows for a maximum of one relationship hop followed by a terminal attribute (e.g., primary_address.address).

Relationship Rules

• Cardinality: The resolver only supports single-cardinality relationships. If a path encounters a relation with many cardinality, it raises a RuntimeError.
• IP Processing: The system includes a value_mapper specifically for IPHost kinds, which converts ip_interface objects to bare IP strings without prefix lengths.

Sources: nornir_infrahub/plugins/inventory/infrahub.py:30-49, dev/knowledge/inventory-data-model.md

Inventory Loading Process

The load() method assembles the final Nornir Inventory object by combining static files, SDK resources, and resolved mappings.

Host Data Contract

Every host in the inventory contains a reference to its source Infrahub node under host.data["InfrahubNode"]. This object carries the bound _client, allowing task plugins to perform operations (like artifact generation) using the same connection and authentication context.
Sources: dev/knowledge/architecture.md, dev/knowledge/infrahub-sdk-integration.md, nornir_infrahub/plugins/inventory/infrahub.py:288

Group Derivation

Groups are generated from two distinct sources:

1. Direct Membership: The plugin reads the member_of_groups relationship. It specifically looks for peers where typename == "CoreStandardGroup".
2. Mapped Groups: The group_mappings configuration generates groups based on node attributes. These are formatted as {first_path_segment}__{slugified_value} (e.g., site__paris-hq).

Sources: dev/knowledge/inventory-data-model.md, nornir_infrahub/plugins/inventory/infrahub.py:291-310

Implementation Details

Construction-Time Validation

The plugin validates mappings during __init__ before querying Infrahub. It checks if the first hop of a multi-part mapping exists as a valid relationship on the host kind. It then merges these required relationships into the include list to ensure the SDK hydrates the necessary related objects in a single query.
Sources: nornir_infrahub/plugins/inventory/infrahub.py:206-225, dev/knowledge/inventory-data-model.md

Error Handling

Scenario	Action	Source
Multi-hop path (>2 segments)	Raises ValueError	infrahub.py:212
Invalid relationship name	Raises ValueError	infrahub.py:217
Many-cardinality relation	Raises RuntimeError	infrahub.py:38
"name" mapping failure	Raises RuntimeError	infrahub.py:270
Attribute mapping failure	Swallows error (Omit property)	infrahub.py:285

The Inventory Data Model ensures a structured and validated flow of data from Infrahub's graph-based storage into Nornir's flat host/group structure, maintaining efficiency through relation pre-fetching and SDK store population.
Sources: dev/knowledge/architecture.md, dev/knowledge/inventory-data-model.md