Using the Inventory Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The InfrahubInventory plugin connects Nornir to the Infrahub API to transform infrastructure data into Nornir hosts and groups. It uses the infrahub-sdk to fetch nodes from a specific branch and maps their attributes and relationships to host properties via configurable schema mappings.
The plugin functions as an entry point within the Nornir framework, allowing for direct integration via configuration files or Python scripts. It facilitates automated group creation based on node attributes, standard Infrahub groups, and relationship paths.
Sources: nornir_infrahub/plugins/inventory/infrahub.py:129-138, dev/knowledge/architecture.md:6-10
Plugin Registration and Initialization
The inventory plugin is registered as a Nornir entry point under the name InfrahubInventory. Nornir discovers this plugin automatically when the package is installed.
This diagram shows the registration and early initialization flow of the inventory plugin.
Sources: pyproject.toml:27-28, dev/guides/using-the-inventory-plugin.md:7-14
Configuration Parameters
The plugin accepts several options through the Nornir inventory dictionary or config.yaml file.
| Parameter | Type | Default | Description |
|---|---|---|---|
address | str | http://localhost:8000 | The Infrahub API URL. |
token | str | None | API token for authentication. |
branch | str | main | The Infrahub branch to query. |
host_node | dict | Required | Defines the node kind and filters for hosts. |
schema_mappings | list | [] | Maps node attributes to Nornir host properties. |
group_mappings | list | [] | Paths to create groups (e.g., site.name). |
defaults_file | str | defaults.yaml | Path to static Nornir defaults. |
group_file | str | group.yaml | Path to static Nornir groups. |
Sources: nornir_infrahub/plugins/inventory/infrahub.py:180-192, dev/guides/using-the-inventory-plugin.md:21-46
Inventory Loading Process
The load() method executes the data retrieval and mapping logic. It performs a single host fetch using include= parameters derived from mappings to hydrate related nodes in one request.
This sequence diagram illustrates the communication between the plugin, the SDK, and the Infrahub API during inventory loading.
Sources: dev/knowledge/inventory-data-model.md:46-64, nornir_infrahub/plugins/inventory/infrahub.py:233-312
Mapping Logic and Constraints
The plugin enforces strict rules for resolving data paths:
- Hop Limit: Mappings can span at most one relationship hop (e.g.,
primary_address.address). Paths with more than one dot raise aValueError. - Cardinality: Relations with
manycardinality are not supported for host property mapping and raise aRuntimeError. - Special Handling: Attributes of kind
IPHostare automatically converted to bare IP strings without prefix lengths.
Sources: nornir_infrahub/plugins/inventory/infrahub.py:26, nornir_infrahub/plugins/inventory/infrahub.py:34-49, dev/knowledge/inventory-data-model.md:21-31
Group Derivation
The plugin generates Nornir groups from three distinct sources to organize hosts effectively.
Group Sources and Naming
- Static Groups: Loaded from the file specified in
group_file. - Standard Groups: Hosts are automatically added to groups corresponding to their
member_of_groupspeers of typeCoreStandardGroup. - Derived Groups: The
group_mappingsoption creates groups using the format<first_part>__<slugified-value>. For example, asite.namemapping resolving to "Paris HQ" creates a group namedsite__paris-hq.
This diagram visualizes how various data sources in Infrahub are consolidated into Nornir groups.
Sources: dev/knowledge/inventory-data-model.md:66-77, nornir_infrahub/plugins/inventory/infrahub.py:291-310, dev/guides/using-the-inventory-plugin.md:52-57
SDK Integration and Authentication
The plugin initializes an InfrahubClientSync during construction. This client is stored within each host at host.data["InfrahubNode"]. Task plugins use this stored node and its bound client to perform operations like artifact generation or file uploads.
Authentication Fallback
If the token or address are not explicitly provided in the plugin options, the infrahub-sdk falls back to environment variables defined in its own configuration.
Sources: dev/knowledge/infrahub-sdk-integration.md:9-17, nornir_infrahub/plugins/inventory/infrahub.py:288, dev/guides/using-the-inventory-plugin.md:65-79
Summary
The InfrahubInventory plugin provides a structured bridge between Infrahub's graph database and Nornir's automation framework. By validating schema mappings at initialization and automatically hydrating required relationships, it ensures efficient data retrieval. The inclusion of the InfrahubNode object in host data allows downstream task plugins to reuse the authenticated SDK session for subsequent infrastructure management tasks.
Sources: dev/knowledge/architecture.md:37-45, dev/knowledge/infrahub-sdk-integration.md:39-49