System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
nornir-infrahub integrates the Nornir automation framework with the Infrahub data management platform. The system operates through two primary components: an inventory plugin that transforms Infrahub nodes into Nornir hosts, and a collection of task plugins that manage Infrahub artifacts and file objects. Both components interact with the Infrahub API exclusively through the infrahub-sdk.
Sources: dev/knowledge/architecture.md:1-8, AGENTS.md:7-12
Core Components and Contracts
The architecture relies on a shared data contract between the inventory and task plugins. The inventory plugin stores the original Infrahub node object within the Nornir host's data structure under the key InfrahubNode. Task plugins access this key to retrieve the node data and the authenticated SDK client required for their operations.
Sources: dev/knowledge/architecture.md:9-10, dev/knowledge/infrahub-sdk-integration.md:46-51
High-Level Architecture Flow
The following diagram illustrates the data flow from the Infrahub API through the SDK to the Nornir inventory and subsequent task execution.
The diagram shows the sequence of node retrieval, host mapping, and the reuse of the SDK client by task plugins.
Sources: dev/knowledge/architecture.md:94-126, dev/knowledge/infrahub-sdk-integration.md:53-59
Inventory Plugin Architecture
The InfrahubInventory plugin manages the transformation of Infrahub nodes into Nornir hosts and groups. It uses Pydantic models to validate configuration and the synchronous InfrahubClientSync to perform queries.
Sources: dev/knowledge/architecture.md:12-16, dev/knowledge/infrahub-sdk-integration.md:11-15
Mapping and Resolution Logic
The plugin resolves host properties and group memberships based on schema_mappings and group_mappings. It enforces a relationship hop limit (MAX_RELATIONSHIP_HOPS = 2) to ensure performance, allowing at most one relationship traversal per mapping (e.g., primary_address.address).
Sources: dev/knowledge/inventory-data-model.md:37-45, dev/knowledge/architecture.md:25-27
| Configuration Key | Description | Data Structure |
|---|---|---|
host_node | Defines the node kind to map to Nornir hosts. | HostNode (Pydantic Model) |
schema_mappings | Maps Nornir host properties to Infrahub node attributes or relations. | List of SchemaMappingNode |
group_mappings | Defines paths used to derive Nornir groups dynamically. | List of strings |
defaults_file | Path to a YAML file seeding Nornir defaults. | String (Path) |
Sources: dev/knowledge/architecture.md:18-32, dev/knowledge/inventory-data-model.md:11-30
Group Derivation Logic
The system builds Nornir groups from two distinct sources:
- CoreStandardGroup: Direct membership in Infrahub groups via the
member_of_groupsrelation. - Dynamic Mappings: Attribute or relation values derived from
group_mappings(e.g.,site.namebecomingsite__jfk1).
Task Plugin System
Task plugins are synchronous functions that perform operations against Infrahub using the node stored in host.data["InfrahubNode"]. They return a Nornir Result object to indicate success, failure, or state changes.
Sources: dev/guides/developing-a-task-plugin.md:5-15, dev/knowledge/architecture.md:54-58
Artifact and File Management
Tasks are divided into two functional modules:
- Artifact Tasks: Manage generated documents like device configurations and compliance reports using SDK methods like
artifact_generate()andobject_store.get(). - File Object Tasks: Perform idempotent uploads and downloads of binary content for nodes inheriting from
CoreFileObject.
Sources: dev/knowledge/architecture.md:59-78, AGENTS.md:11-12
Task Execution Sequence
Transport Layer: Infrahub SDK Integration
The system uses the infrahub-sdk exclusively for communication. It avoids raw HTTP calls, relying on the SDK's client store and GraphQL generation capabilities.
Sources: dev/knowledge/infrahub-sdk-integration.md:7-9, AGENTS.md:66-67
- Synchronous Client: The inventory creates one
InfrahubClientSyncinstance. - Authentication: Uses an API token provided via configuration or environment variables.
- Branch Awareness: All queries and task operations respect the
default_branchconfiguration, allowing operations on non-main branches. - Object Store: Manages binary transfers and checksum comparisons for file objects.
Sources: dev/knowledge/infrahub-sdk-integration.md:11-28, dev/knowledge/architecture.md:133-136
Summary
The nornir-infrahub architecture centralizes Infrahub interaction through a single SDK client managed by the inventory plugin. By embedding this client and the source node data into Nornir's inventory, the system ensures that all subsequent automation tasks maintain consistent authentication, branch context, and data access. This structure supports both complex inventory mapping and idempotent artifact management within the standard Nornir workflow.
Sources: dev/knowledge/architecture.md:1-11, dev/knowledge/infrahub-sdk-integration.md:46-59