Artifact Management Modules

Relevant source files

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

• plugins/modules/artifact_generate.py
• plugins/modules/artifact_fetch.py
• dev/guides/creating-a-module.md
• dev/knowledge/plugin-patterns.md
• plugins/module_utils/infrahub_utils.py
• dev/constitution.md

Artifact Management Modules provide the interface for interacting with Infrahub artifacts within Ansible playbooks. These modules allow you to retrieve existing artifact content and trigger the regeneration of artifacts associated with specific target nodes.

These modules follow the Action Plugin Pattern, where the module file serves as a documentation stub and argument validator, while the actual API execution logic resides in a corresponding action plugin running on the Ansible controller.
Sources: dev/constitution.md:27-31, dev/guides/creating-a-module.md:12-15

Module Architecture and Patterns

Artifact modules utilize a split architecture between module stubs and action plugins. This design ensures that complex API calls and SDK interactions occur on the controller rather than the managed nodes.

Action Plugin Pattern

The artifact modules (fetch and generate) do not use the standard InfrahubModule subclass pattern found in stateful modules like node or branch. Instead, they leverage ActionModule(ActionBase) to perform controller-side API calls.
Sources: dev/constitution.md:27-31, dev/knowledge/plugin-patterns.md:73-77

The diagram shows the flow from a playbook through the controller-side action plugin to the Infrahub API.
Sources: dev/guides/creating-a-module.md:92-105, dev/constitution.md:27-31

Shared Configuration

All artifact modules extend a standard set of Infrahub connection parameters defined in INFRAHUB_ARG_SPEC. This ensures consistent handling of credentials, endpoints, and timeouts.
Sources: plugins/modules/artifact_generate.py:150-155, dev/knowledge/plugin-patterns.md:52-59

Parameter	Type	Default	Description
api_endpoint	str	None	Endpoint of the Infrahub API (env: INFRAHUB_ADDRESS).
token	str	None	API token (env: INFRAHUB_API_TOKEN). Marked no_log=True.
timeout	int	10	Timeout for Infrahub requests in seconds.
branch	str	main	Branch in which the request is made.
validate_certs	bool	True	Whether to validate SSL certificates.
Sources: plugins/modules/artifact_fetch.py:19-54, plugins/modules/artifact_generate.py:23-64

Artifact Fetching

The artifact_fetch module retrieves the content of an artifact from Infrahub. It supports multiple identification methods for locating the desired artifact.

Identification Logic

You must identify the artifact using one of the following combinations:

• artifact_name AND target_id
• artifact_id (UUID)

The module enforces mutual exclusivity between artifact_name and artifact_id.
Sources: plugins/modules/artifact_fetch.py:100-103

Returned Data

When successful, the module returns the artifact content in two formats:

1. json: The content parsed as a dictionary.
2. text: The raw content as a string.
   Sources: plugins/modules/artifact_fetch.py:84-93

Artifact Generation

The artifact_generate module triggers a regeneration of an artifact for a specified target node. This is used to refresh dynamic content like configuration files or documentation based on current data in the Infrahub graph.

Operation Logic

1. Validation: The module checks for required parameters, ensuring target_id is present and either artifact_name or artifact_id is provided.
2. API Call: The action plugin triggers a regeneration request to the Infrahub API for the specific artifact-target pair.
3. Result Reporting: The module reports whether a change occurred and returns identification metadata for the processed artifact.
   Sources: plugins/modules/artifact_generate.py:18-22, plugins/modules/artifact_generate.py:126-146

The sequence shows the process of triggering an artifact regeneration via the Action Plugin.
Sources: dev/guides/creating-a-module.md:124-142, plugins/modules/artifact_generate.py:126-146

Implementation Details

Mutual Exclusion and Requirements

The artifact modules use AnsibleModule validation logic to ensure correct argument combinations at the start of execution.
Sources: plugins/modules/artifact_fetch.py:100-116, plugins/modules/artifact_generate.py:157-161

# From plugins/modules/artifact_fetch.py
required_together = [("artifact_name", "target_id")]
mutually_exclusive = [("artifact_name", "artifact_id"), ("artifact_id", "target_id")]
required_one_of = [("artifact_name", "artifact_id")]
AnsibleModule(
    argument_spec=dict(...),
    required_together=required_together,
    mutually_exclusive=mutually_exclusive,
    required_one_of=required_one_of,
    supports_check_mode=False,
)

Sources: plugins/modules/artifact_fetch.py:100-116

SDK Integration

All API access is mediated through the InfrahubclientWrapper in plugins/module_utils/infrahub_utils.py. The action plugins check for the presence of the infrahub-sdk library using a HAS_INFRAHUBCLIENT guard before attempting to instantiate the client.
Sources: dev/constitution.md:43-46, dev/guides/creating-a-module.md:112-114, plugins/module_utils/infrahub_utils.py

Artifact Management Modules facilitate the retrieval and lifecycle management of infrastructure artifacts by providing a standardized controller-side interface to the Infrahub API.