Node Management Module
Relevant source files
The following files were used as context for generating this wiki page:
The Node Management Module provides the primary interface for creating, updating, and deleting infrastructure nodes within Infrahub. It manages arbitrary node types (Kinds) defined in the Infrahub schema and ensures stateful, idempotent operations by comparing desired state against the current live data in the platform.
This module follows the Module Utils Pattern, where a lightweight user-facing stub delegates execution to a specialized logic class. This architecture supports advanced Ansible features such as check_mode, --diff reporting, and Human-Friendly ID (HFID) normalization.
Sources: dev/knowledge/architecture.md, dev/constitution.md:29-34, plugins/modules/node.py:15-18
Architecture and Design
The Node Management Module consists of two primary components: the module stub and the implementation class. The stub defines the user-facing argument schema, while the implementation class manages the lifecycle of Infrahub nodes.
Component Interaction
The following diagram illustrates the data flow when a user executes a task using the node module.
The logic resides in the NodeModule class, which inherits from InfrahubModule. This base class handles the core fetch-compare-act cycle required for idempotency.
Sources: dev/knowledge/architecture.md:65-72, plugins/module_utils/node.py:12-14, dev/constitution.md:43-52
Module Configuration and Options
The module utilizes a standard set of Infrahub connection parameters extended with node-specific data.
Argument Specification
The module merges the base INFRAHUB_ARG_SPEC with specific parameters for node identification and data payloads.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
kind | str | Yes | - | The Kind of node to manage in Infrahub. |
data | raw | Yes | - | Dictionary of node attributes and relationships. |
state | str | No | present | Use present to ensure existence or absent to remove. |
api_endpoint | str | No | None | Infrahub API URL. Falls back to INFRAHUB_ADDRESS. |
token | str | No | None | API Token. Falls back to INFRAHUB_API_TOKEN. |
branch | str | No | main | The Infrahub branch for the operation. |
file_path | str | No | None | Local path for CoreFileObject uploads. |
fetch_file | bool | No | false | Whether to download content for CoreFileObject nodes. |
Sources: plugins/modules/node.py:27-86, plugins/module_utils/infrahub_utils.py, dev/guides/creating-a-module.md:129-136
Operational Logic and Idempotency
The module ensures idempotency by implementing a structured execution flow. It avoids unnecessary API mutations by comparing the local data dictionary against existing server-side objects.
State Transitions
The InfrahubModule base class provides two main methods for state management: _ensure_object_exists and _ensure_object_absent.
File Handling
For nodes inheriting from CoreFileObject, the module supports idempotent file uploads. It calculates a SHA-1 checksum of the local file and compares it to the server-side checksum. If the checksums match, the module skips the upload to maintain idempotency.
Sources: plugins/modules/node.py:68-75
Implementation Details
The NodeModule class implements the run() method required by the InfrahubModule interface.
# plugins/module_utils/node.py:12-21
class NodeModule(InfrahubModule):
def run(self) -> None:
kind = self.module.params["kind"]
data = self.module.params["data"]
file_path = self.module.params.get("file_path")
fetch_file = self.module.params.get("fetch_file")
if self.state == "present":
self._ensure_object_exists(kind=kind, data=data, file_path=file_path, fetch_file=fetch_file)
else:
self._ensure_object_absent(kind=kind, data=data)
The InfrahubclientWrapper mediates all communication with the SDK. It translates standard SDK exceptions, such as GraphQLError or BranchNotFoundError, into user-friendly Ansible error messages via a specialized decorator.
Sources: plugins/module_utils/node.py:12-21, dev/constitution.md:43-52, plugins/module_utils/infrahub_utils.py
Summary
The Node Management Module provides a robust, state-oriented way to manage Infrahub data. By leveraging the InfrahubModule base class and the InfrahubclientWrapper, it maintains strict idempotency, handles complex CoreFileObject logic, and provides detailed diffing capabilities for infrastructure-as-code workflows.