Uploading Files Guide

Relevant source files

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

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

This guide describes how to use the file-object task plugins in nornir-infrahub to manage file content between a local environment and the Infrahub object store. These plugins support moving data for Infrahub nodes that inherit from the CoreFileObject base kind.

The file-object system provides two primary Nornir tasks: upload_file_object and download_file_object. Both tasks are checksum-driven and idempotent, ensuring that transfers only occur when local and remote content differ.

Sources: dev/guides/uploading-files.md:1-5, nornir_infrahub/plugins/tasks/file_object.py:90-95, dev/knowledge/architecture.md:46-51

Task Architecture and Requirements

The file-object tasks rely on the Nornir inventory being populated by the InfrahubInventory plugin. This is because the tasks retrieve the authenticated Infrahub SDK client directly from the host data.

• Host Data Contract: Each Nornir host must contain an InfrahubNodeSync object stored at task.host.data["InfrahubNode"].
• SDK Integration: The tasks use node._client to access the Infrahub API and object store.
• Schema Inheritance: Target nodes must inherit from CoreFileObject. The tasks validate this inheritance at runtime and fail if the condition is not met.

Sources: dev/guides/uploading-files.md:9-16, dev/knowledge/infrahub-sdk-integration.md:44-53, nornir_infrahub/plugins/tasks/file_object.py:40-44

Data Flow Diagram

The following diagram illustrates the interaction between Nornir, the task plugins, and the Infrahub SDK during a file operation.

The diagram shows how the task plugins access the SDK client through the host data to communicate with the Infrahub Object Store.

Sources: dev/knowledge/architecture.md:65-90, dev/knowledge/infrahub-sdk-integration.md:58-69

Uploading Files

The upload_file_object task creates or updates an Infrahub object with file content. It supports uploading from a local filesystem path or providing raw bytes directly in memory.

Functionality and Idempotency

1. Source Resolution: You must provide exactly one of file_path or content.
2. Checksum Comparison: The task compares the local SHA-1 checksum against the server-side checksum.
3. Transfer Logic: If the checksums match, the upload is skipped (changed=False). If they differ, the file is uploaded (changed=True).
4. Attribute Updates: If the file is unchanged but the attributes in data differ, the task updates the attributes and returns changed=True.

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

Configuration Parameters

Parameter	Type	Description
kind	str	The Infrahub schema kind (must inherit from CoreFileObject).
file_path	str | Path	Local path to the file. Mutually exclusive with content.
content	bytes	Raw bytes to upload. Requires file_name.
file_name	str	Name associated with content. Required if content is used.
data	dict	Additional attributes for the object.
object_id	str	UUID of an existing object to update.
hfid	list[str]	HFID components to identify an existing object.

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

Downloading Files

The download_file_object task retrieves file content from an Infrahub object. It returns binary data and, if the file is a recognized text type, a UTF-8 string representation.

Download Logic

• Identification: The object must be identified using either object_id or hfid.
• Text Handling: Recognition is based on MIME types. Recognized types include text/plain, text/markdown, application/json, application/yaml, and application/xml.
• Local Saving: If save_to is provided, the task writes the file to the local disk. It skips writing if a local file with the same checksum already exists.

Sources: nornir_infrahub/plugins/tasks/file_object.py:15-28, nornir_infrahub/plugins/tasks/file_object.py:256-291, dev/guides/uploading-files.md:58-75

Sequence of Download Operation

The sequence shows the checksum-aware logic that minimizes unnecessary downloads when saving to disk.

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

Error Handling

Unlike artifact tasks, file-object tasks catch SDK and validation errors. Instead of raising exceptions that halt the Nornir execution, they return a Result object where failed=True.

• Validation Failures: Providing both file_path and content returns a failed Result.
• Kind Validation: Using a kind that does not inherit from CoreFileObject returns a failed Result.
• Lookup Misses: If an object identified by object_id or hfid is not found, the task returns Result(failed=True).

Sources: nornir_infrahub/plugins/tasks/file_object.py:147-169, dev/guides/uploading-files.md:83-93, dev/knowledge/infrahub-sdk-integration.md:92-96

Summary

The file-object task plugins provide an idempotent way to synchronize files with Infrahub. By utilizing the InfrahubNode contract and the underlying SDK, these tasks handle complex object-store interactions while exposing a simplified interface to Nornir users. Both upload_file_object and download_file_object prioritize efficiency through SHA-1 checksum verification.

Sources: dev/guides/uploading-files.md:1-7, dev/knowledge/architecture.md:55-63