Infrahub SDK Integration
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub SDK Integration provides the transport layer for the nornir-infrahub plugin to communicate with an Infrahub instance. The project uses the infrahub-sdk library to manage all API interactions, including inventory fetching, artifact management, and file object transfers.
This integration eliminates raw HTTP requests in favor of high-level SDK methods. It establishes a shared client contract that allows task plugins to reuse the authenticated connection initialized by the inventory plugin.
Sources: dev/knowledge/infrahub-sdk-integration.md:1-12, dev/knowledge/architecture.md:5-10
Client Architecture and Lifecycle
The plugin uses the synchronous version of the SDK, InfrahubClientSync, because Nornir tasks and inventory loading operate in a synchronous execution model. There is exactly one authenticated client instance per Nornir run.
Client Initialization
The InfrahubInventory class initializes the client during its __init__ phase. It uses an API token and a server address, falling back to SDK environment variables if these are not explicitly provided in the Nornir configuration.
Sources: dev/knowledge/infrahub-sdk-integration.md:14-23, nornir_infrahub/plugins/inventory/infrahub.py:198
The SDK Node Contract
When the inventory plugin fetches data, it stores the resulting InfrahubNodeSync objects within the Nornir Host data structure. This establishes a shared contract that task plugins use to access the Infrahub API without re-authenticating.
The diagram shows the lifecycle of the SDK client from initialization in the inventory to reuse in task plugins.
Sources: dev/knowledge/infrahub-sdk-integration.md:46-56, dev/knowledge/architecture.md:75-80
Core SDK Operations
The integration utilizes specific SDK components for different automation requirements.
Inventory and Schema Management
The inventory plugin performs two primary types of queries:
- Schema Fetching: Retrieves the kind's schema to validate user-defined mappings before fetching data.
- Resource Fetching: Uses
client.filters()withpopulate_store=Trueto retrieve nodes and cache relations.
Sources: dev/knowledge/infrahub-sdk-integration.md:32-44, nornir_infrahub/plugins/inventory/infrahub.py:206
Artifact and File Management
Task plugins leverage the SDK's specialized methods for handling generated content and binary data.
| Task | SDK Method / Path |
|---|---|
regenerate_host_artifact | node.artifact_generate() |
generate_artifacts | artifact_definition.generate() |
get_artifact | client.object_store.get() |
upload_file_object | client.create() + upload_if_changed() |
download_file_object | obj.download_file() + matches_local_checksum() |
Sources: dev/knowledge/infrahub-sdk-integration.md:65-76, dev/knowledge/architecture.md:40-52
Data Mapping and Resolution
The integration supports dotted-path resolution for Infrahub node attributes and relationships. The resolution logic is capped at one relation hop to maintain performance and avoid deep recursive queries.
Resolution Logic
The resolve_node_mapping function traverses the SDK node structure:
- Attributes: Direct values are read from
node.attribute.value. - Relationships: The plugin accesses the
peerof a relation. Only relations with a cardinality of "one" are supported. - Value Mapping: The integration automatically converts complex types, such as
IPHost, into standard strings (e.g., stripping prefix lengths from IP interfaces).
Sources: dev/knowledge/inventory-data-model.md:46-64, nornir_infrahub/plugins/inventory/infrahub.py:34-49
Relationship Pre-fetching
To prevent extra API round trips during mapping resolution, the plugin automatically identifies required relations and adds them to the include parameter of the SDK query. The member_of_groups relation is always included by default to support group derivation.
Sources: nornir_infrahub/plugins/inventory/infrahub.py:106-116, dev/knowledge/inventory-data-model.md:14-25
Branch Handling
The SDK integration treats branching as a first-class feature. The branch configuration is passed to the SDK Config and used as the default_branch for the client.
- The inventory plugin uses this branch for all initial node and schema fetches.
- Task plugins (specifically file object tasks) allow overriding the branch on a per-call basis.
- If no branch is specified, the SDK client defaults to
"main".
Sources: dev/knowledge/infrahub-sdk-integration.md:25-30, nornir_infrahub/plugins/inventory/infrahub.py:184
Error Handling and Exception Mapping
The integration handles SDK exceptions differently depending on the plugin type:
| Plugin Type | Handling Strategy | Result |
|---|---|---|
| Inventory | Raises ValueError or RuntimeError | Aborts inventory load for fatal configuration errors; skips properties for resolution failures. |
| Artifact Tasks | Propagates SDK exceptions | Nornir task fails and error bubbles up to the runner. |
| File Tasks | Catches SDK exceptions | Returns Result(failed=True) to prevent the entire Nornir run from stopping. |
Sources: dev/knowledge/infrahub-sdk-integration.md:86-97, dev/knowledge/architecture.md:32-38
Summary
The Infrahub SDK integration centralizes communication through a synchronous client shared between inventory and task plugins. By utilizing the InfrahubNodeSync contract, the project ensures consistent access to the Infrahub graph, supports version control through native branch handling, and provides idempotent file operations using the SDK's object store capabilities.
Sources: dev/knowledge/architecture.md:1-10, AGENTS.md:73-77