Artifact Task Plugin

Relevant source files

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

• nornir_infrahub/plugins/tasks/artifact.py
• dev/guides/managing-artifacts.md
• dev/knowledge/architecture.md
• dev/knowledge/infrahub-sdk-integration.md
• dev/guides/developing-a-task-plugin.md
• AGENTS.md

The Artifact Task Plugin provides a set of Nornir tasks to manage Infrahub artifacts, such as device configurations and compliance reports. These tasks interface with the Infrahub SDK to generate, regenerate, and retrieve artifact content stored in the Infrahub object store.

This module acts as the "second half" of the nornir-infrahub integration, relying on the Inventory Plugin to populate host data with Infrahub node references. All tasks in this plugin expect each Nornir host to contain an InfrahubNode object in its host.data dictionary.

Sources: dev/knowledge/architecture.md, AGENTS.md, dev/guides/managing-artifacts.md

Architecture

The artifact tasks operate as synchronous Python functions. They follow the standard Nornir task protocol by accepting a Task object as the first argument and returning a Result object.

The Host Data Contract

The integration relies on a specific data contract where the Infrahub inventory plugin stores an InfrahubNodeSync object under the key InfrahubNode in the Nornir host's data attribute. The task plugins extract this node to access the Infrahub API client and node-specific methods.

The diagram shows how tasks reach the Infrahub SDK through the host's data.
Sources: dev/knowledge/architecture.md, dev/guides/developing-a-task-plugin.md

SDK Integration

Artifact tasks perform operations through the infrahub-sdk. Historically, these tasks used raw REST calls via httpx, but they have been migrated to use SDK-provided functions like node.artifact_generate() and client.object_store.get().

Sources: dev/knowledge/infrahub-sdk-integration.md, CHANGELOG.md

Core Task Functions

The plugin provides three primary tasks for artifact management.

get_artifact

This task retrieves a CoreArtifact and downloads its content from the Infrahub object store. You must provide exactly one identifier: either the artifact name (matched against the host node) or a specific artifact_id. If the content type is application/json, the task parses the result into a Python object; otherwise, it returns the content as text.

Sources: dev/guides/managing-artifacts.md, nornir_infrahub/plugins/tasks/artifact.py:118-181

generate_artifacts

This task triggers the generation of artifacts for a specific CoreArtifactDefinition. Because a definition typically targets multiple nodes, this task generates artifacts for all associated targets. It is recommended to run this task once per definition by filtering the Nornir run to a single host.

Sources: dev/guides/managing-artifacts.md, nornir_infrahub/plugins/tasks/artifact.py:65-115

regenerate_host_artifact

This task regenerates a named artifact specifically for the individual host. It calls the artifact_generate method directly on the host's InfrahubNode.

Sources: dev/guides/managing-artifacts.md, nornir_infrahub/plugins/tasks/artifact.py:16-62

Task Parameters and Returns

Task	Parameter	Type	Description
regenerate_host_artifact	artifact	str	Name of the artifact to regenerate for the host.
generate_artifacts	artifact	str	Name of the CoreArtifactDefinition to trigger.
	timeout	int	Ignored (retained for backward compatibility).
get_artifact	artifact	Optional[str]	Name of the artifact associated with the host.
	artifact_id	Optional[str]	Unique ID of the CoreArtifact node.

Result Data Structure

Tasks return a Nornir Result object. The result attribute of this object varies by task:

• get_artifact: Contains the downloaded content (string or dict). It also includes a custom content_type attribute.
• generate_artifacts / regenerate_host_artifact: The result attribute is typically empty, but failed is set to False on success.

Sources: dev/guides/managing-artifacts.md, nornir_infrahub/plugins/tasks/artifact.py

Implementation Logic

The following sequence diagram illustrates the internal flow when get_artifact is called.

The sequence shows the retrieval process from host data through the SDK to the API.
Sources: nornir_infrahub/plugins/tasks/artifact.py:167-178, dev/knowledge/architecture.md

Error Handling

Artifact tasks generally allow SDK exceptions to propagate to Nornir, which marks the host's result as failed. However, specific validation checks within the tasks will raise a RuntimeError:

• In get_artifact, providing both artifact and artifact_id, or providing neither, raises a RuntimeError.
• Missing the InfrahubNode in host data results in a KeyError.

Sources: dev/guides/developing-a-task-plugin.md, dev/guides/managing-artifacts.md, nornir_infrahub/plugins/tasks/artifact.py:161-164

Summary

The Artifact Task Plugin enables seamless management of Infrahub-generated data within Nornir workflows. By utilizing the InfrahubNode contract established by the inventory plugin, these tasks provide high-level abstractions for regenerating configurations and fetching stored objects without requiring manual API or GraphQL construction.