File Object Task Plugin

Relevant source files

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

• nornir_infrahub/plugins/tasks/file_object.py
• dev/guides/uploading-files.md
• dev/knowledge/architecture.md
• dev/knowledge/infrahub-sdk-integration.md
• AGENTS.md
• dev/guides/developing-a-task-plugin.md

The File Object Task Plugin manages file content transfers between a local environment and the Infrahub object store. It provides Nornir tasks to upload and download files associated with Infrahub nodes that inherit from the CoreFileObject base kind. These tasks ensure idempotency through SHA-1 checksum comparisons, skipping unnecessary transfers when local and remote content matches.

Sources: dev/guides/uploading-files.md, CHANGELOG.md

Architecture and Integration

The plugin integrates with the Infrahub SDK to perform synchronous operations. It relies on the project's core contract where the inventory plugin populates each Nornir host with an InfrahubNodeSync object.

The Host Contract

Every file-object task expects the target Nornir host to contain an active Infrahub node reference. The inventory plugin assigns this reference to host.data["InfrahubNode"]. The task plugins extract the authenticated SDK client directly from this node to perform API calls.

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

Data Flow Overview

The following diagram illustrates the interaction between the Nornir Task, the Infrahub SDK, and the remote Infrahub instance.

The diagram shows how the task leverages host data to access the SDK and interact with the remote object store.
Sources: dev/knowledge/architecture.md, dev/knowledge/infrahub-sdk-integration.md

Upload Task Logic

The upload_file_object task handles the creation or update of file-based nodes. It accepts either a filesystem path or raw bytes as input.

Idempotency and Checksums

The task uses SHA-1 checksums to determine if an upload is necessary. If the server-side checksum matches the local content, the task skips the upload and sets changed=False. If the checksum differs, the task uploads the content and sets changed=True. If the file content matches but other metadata in data or **kwargs differs, the task updates the attributes and marks the result as changed.

Sources: dev/guides/uploading-files.md, dev/knowledge/infrahub-sdk-integration.md

Upload Parameters

Parameter	Type	Description
kind	str	The Infrahub node kind (must inherit from CoreFileObject).
file_path	str	Path to the local file to upload.
content	bytes	Raw binary content (alternative to file_path).
file_name	str	Name of the file (required if using content).
data	dict	Additional attributes for the Infrahub node.
object_id	str	Specific UUID of the Infrahub object.
hfid	list	Human Friendly Identifier for the object.
branch	str	Target Infrahub branch for the operation.

Sources: dev/guides/uploading-files.md, nornir_infrahub/plugins/tasks/file_object.py

Download Task Logic

The download_file_object task retrieves content from the Infrahub object store. It identifies objects using either a unique ID or an HFID.

Content Handling

The task returns content in the Nornir Result object. It decodes text-based MIME types (like text/plain) into the result.text field. Binary content remains base64-encoded in the result.binary field. If you provide the save_to parameter, the task writes the content to the local disk.

Sources: dev/guides/uploading-files.md, CHANGELOG.md

Download Process Flow

This sequence shows the retrieval of node metadata followed by the binary download from the object store.
Sources: dev/guides/uploading-files.md, dev/knowledge/infrahub-sdk-integration.md

Error Handling

Unlike artifact tasks, file object tasks catch exceptions to prevent Nornir execution from halting. The tasks return a Result with failed=True and an error message for the following conditions:

• The kind does not inherit from CoreFileObject.
• Invalid argument combinations (e.g., providing both file_path and content).
• The target node is not found in Infrahub.
• The SDK throws a communication or validation error.

Sources: dev/guides/uploading-files.md, dev/knowledge/infrahub-sdk-integration.md, dev/guides/developing-a-task-plugin.md

Usage Example

The following snippet demonstrates how to call the upload task within a Nornir workflow.

from nornir_infrahub.plugins.tasks import upload_file_object

def sync_contracts(task):
    task.run(
        task=upload_file_object,
        kind="NetworkCircuitContract",
        file_path=f"contracts/{task.host.name}.pdf",
        data={"status": "active"}
    )

Sources: dev/guides/uploading-files.md, dev/guides/developing-a-task-plugin.md

The File Object Task Plugin provides a robust, idempotent mechanism for managing binary and text assets in Infrahub. By utilizing SHA-1 checksums and integrated SDK methods like upload_if_changed, it optimizes network usage and maintains state consistency across infrastructure automation runs.