Nornir-Infrahub Overview
Relevant source files
The following files were used as context for generating this wiki page:
Nornir-Infrahub is a Nornir plugin that integrates the Nornir automation framework with Infrahub by OpsMill. It provides an inventory plugin to fetch network device data and task plugins to manage Infrahub artifacts and file objects.
Sources: README.md:12-14, AGENTS.md:7-10
The integration relies on two primary components:
- An Inventory Plugin that transforms Infrahub nodes into Nornir hosts and groups.
- Task Plugins that manage Infrahub artifacts, such as device configurations and compliance reports.
Sources: dev/knowledge/architecture.md:5-9
System Architecture
The architecture consists of the Infrahub API, the Nornir framework, and the infrahub-sdk which acts as the transport layer. The inventory plugin and task plugins both utilize InfrahubClientSync for communication.
The diagram below illustrates the high-level data flow and relationship between these components:
The shared contract between the inventory and task plugins is the host.data["InfrahubNode"] entry, which stores the original SDK node object on the Nornir host.
Sources: dev/knowledge/architecture.md:46-70, dev/knowledge/infrahub-sdk-integration.md:46-51
Inventory Plugin
The InfrahubInventory class connects to the Infrahub API and maps graph nodes to Nornir hosts. It supports flexible schema mappings to translate node attributes and relationships into Nornir host properties.
Key Features
- Node Mapping: Maps specific Infrahub node kinds (e.g.,
InfraDevice) to Nornir hosts. - Schema Mappings: Translates node attributes (like
primary_address.address) to Nornir host attributes (likehostname). - Group Derivation: Creates Nornir groups from node attributes or relationships (e.g.,
site.name). - Static Overrides: Supports
defaults.yamlandgroup.yamlfor static data and defaults.
Sources: nornir_infrahub/plugins/inventory/infrahub.py:119-140, dev/knowledge/architecture.md:14-25
Inventory Configuration Options
| Option | Type | Description |
|---|---|---|
address | str | URL of the Infrahub API. Default: http://localhost:8000. |
token | str | API token for authentication. |
branch | str | The Infrahub branch to query. Default: main. |
host_node | dict | Defines the node kind, include, exclude, and filters. |
schema_mappings | list | List of {name, mapping} for host property translation. |
group_mappings | list | List of attribute paths to derive Nornir groups. |
Sources: nornir_infrahub/plugins/inventory/infrahub.py:141-149, dev/knowledge/inventory-data-model.md:12-23
Mapping Resolution Logic
The plugin resolves dotted mapping paths (e.g., relation.attribute) through the resolve_node_mapping function. It enforces a limit of two relationship hops.
Resolution Steps
- Splits the mapping string by periods.
- If the segment is a relationship, it traverses to the
peernode. - If the segment is an attribute, it retrieves the value.
- If the attribute is an
IPHost, it converts the value to a string usingip_interface_to_ip_string.
Sources: nornir_infrahub/plugins/inventory/infrahub.py:34-49, dev/knowledge/inventory-data-model.md:37-51
Task Plugins
Task plugins allow Nornir to interact with Infrahub's object store and artifact generation system. These tasks access the SDK client via the InfrahubNode stored in the host data.
Artifact Tasks
These tasks manage generated content within Infrahub:
regenerate_host_artifact: Triggers artifact generation for a specific host node.generate_artifacts: Triggers generation for an entireCoreArtifactDefinition.get_artifact: Downloads artifact content from the object store.
Sources: dev/knowledge/architecture.md:34-44, AGENTS.md:12-14
File Object Tasks
These tasks manage general file storage:
upload_file_object: Uploads file content toCoreFileObjectnodes; performs SHA-1 checksum comparison for idempotency.download_file_object: Downloads content and optionally saves it locally if the checksum differs.
Sources: CHANGELOG.md:25-30, dev/knowledge/architecture.md:41-44
SDK Integration and Transport
All communication with Infrahub is performed using the infrahub-sdk. The plugin utilizes the synchronous client (InfrahubClientSync) to match Nornir's execution model.
The plugin automatically adds required relationships to the include parameter during node fetching. This ensures that the SDK pre-fetches all data needed for mappings in a single request, preventing subsequent "NoneType" errors or extra round trips.
Sources: dev/knowledge/infrahub-sdk-integration.md:9-16, CHANGELOG.md:47-52
Summary
Nornir-Infrahub bridges the gap between Nornir's automation capabilities and Infrahub's versioned infrastructure data. By utilizing the infrahub-sdk, it provides a robust way to populate Nornir inventories and manage infrastructure artifacts directly from a centralized, version-controlled source of truth.
Sources: README.md:15-17, dev/knowledge/architecture.md:104-110