Managing Artifacts Guide

Relevant source files

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

• dev/guides/managing-artifacts.md
• dev/knowledge/architecture.md
• dev/knowledge/infrahub-sdk-integration.md
• AGENTS.md
• dev/guides/developing-a-task-plugin.md
• CHANGELOG.md

This guide describes how to manage Infrahub artifacts using Nornir task plugins. It covers the generation, regeneration, and retrieval of network device configurations, compliance reports, and other documents stored in Infrahub.

Artifact tasks integrate Nornir with the Infrahub object store. These tasks execute against Nornir hosts that represent Infrahub nodes. Each task relies on a specific data contract where the inventory plugin populates task.host.data["InfrahubNode"] with a bound SDK client.
Sources: dev/guides/managing-artifacts.md:1-5, dev/knowledge/architecture.md:39-50

Prerequisites and Integration Architecture

Every artifact task reads the source Infrahub node from the host data. The InfrahubInventory plugin must load the hosts to populate this data; otherwise, tasks raise a KeyError.
Sources: dev/guides/managing-artifacts.md:7-12

Task Data Contract

The following diagram illustrates the relationship between the Inventory, the Nornir Host, and the Artifact Tasks.

The tasks reach the InfrahubClientSync through the stored InfrahubNode. This ensures there is exactly one authenticated client per Nornir run, sharing the address, token, and branch from the inventory.
Sources: dev/knowledge/infrahub-sdk-integration.md:46-56, dev/guides/developing-a-task-plugin.md:20-25

Artifact Task Plugins

The project provides three primary tasks in nornir_infrahub/plugins/tasks/artifact.py. These tasks utilize the infrahub-sdk instead of raw HTTP calls to interact with the Infrahub API.
Sources: dev/guides/managing-artifacts.md:14-20, CHANGELOG.md:46-51

Key Artifact Tasks

Task	Action	SDK Method Used
generate_artifacts	Triggers generation for an entire CoreArtifactDefinition.	artifact_definition.generate()
regenerate_host_artifact	Triggers generation for a specific artifact on a specific host.	node.artifact_generate()
get_artifact	Retrieves the content of a CoreArtifact from the object store.	client.object_store.get()
Sources: dev/guides/managing-artifacts.md:22-50, dev/knowledge/infrahub-sdk-integration.md:65-72

Triggering Artifact Generation

You use generate_artifacts to trigger the generation for all targets defined in a CoreArtifactDefinition. Because this affects all targets, you should typically filter Nornir to a single host before running this task to avoid redundant API calls.
Sources: dev/guides/managing-artifacts.md:22-28

Regenerating Host-Specific Artifacts

The regenerate_host_artifact task calls artifact_generate directly on the host's Infrahub node. This is useful for targeted updates to single devices, such as updating a startup configuration after a change.
Sources: dev/guides/managing-artifacts.md:33-38

Retrieving Artifact Content

The get_artifact task retrieves a CoreArtifact and downloads its stored content. It requires either the artifact name or a specific artifact_id.

If the artifact's content type is application/json, the task parses the result into a Python object. Otherwise, it returns the content as plain text.
Sources: dev/guides/managing-artifacts.md:40-47, dev/knowledge/infrahub-sdk-integration.md:69-72

Task Arguments

Parameter	Type	Required	Description
artifact	str	Conditional	Name of the artifact to fetch for the host.
artifact_id	str	Conditional	Unique ID of the artifact.
timeout	int	No	Retained for compatibility; ignored by SDK path.
Sources: dev/guides/managing-artifacts.md:24-42, CHANGELOG.md:48-51

Handling Task Results

Artifact tasks return a Nornir Result object. You must inspect the AggregatedResult returned by the Nornir run() method to access host-specific data.
Sources: dev/guides/managing-artifacts.md:52-58

• failed: Defaults to False. Artifact tasks let SDK exceptions propagate. If an SDK error occurs, Nornir marks the host result as failed.
• result: Only get_artifact populates this field with the JSON or text content. generate tasks return an empty result on success.
• content_type: get_artifact adds this custom attribute to the Result object to identify the data format.
  Sources: dev/guides/managing-artifacts.md:60-68

# Example: Reading content from get_artifact
for host_name, multi_result in result.items():
    host_result = multi_result[0]
    if not host_result.failed:
        print(f"Host: {host_name}, Type: {host_result.content_type}")
        print(f"Data: {host_result.result}")

Sources: dev/guides/managing-artifacts.md:56-59

Conclusion

Managing artifacts in nornir-infrahub provides a bridge between Nornir's execution framework and Infrahub's versioned object store. By using the provided task plugins, you can automate the lifecycle of infrastructure documentation—from initial generation to final retrieval—while leveraging the idempotency and structured data capabilities of the Infrahub SDK.