Standard Argument Specs & Boilerplate

Relevant source files

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

• plugins/module_utils/infrahub_utils.py
• dev/knowledge/processors-and-arg-spec.md
• plugins/doc_fragments/fragments.py
• dev/constitution.md
• dev/knowledge/plugin-patterns.md
• plugins/AGENTS.md

Standard Argument Specs and Boilerplate define the mandatory structure and common parameters for all plugins within the opsmill.infrahub collection. These standards ensure consistency across different plugin types, including modules, action plugins, and inventory sources, by enforcing required Python imports and shared connection parameters.

The collection utilizes a centralized INFRAHUB_ARG_SPEC to manage connection-related arguments such as API endpoints and tokens. This system reduces code duplication and ensures that all modules maintain a uniform interface for interacting with the Infrahub API. For more details on implementation, see Plugin Patterns.

Sources: dev/constitution.md, plugins/AGENTS.md, dev/knowledge/plugin-patterns.md

Required Python Boilerplate

Every Python file located in the plugins/ directory must include specific boilerplate headers. These headers are mandatory for compatibility and are strictly enforced by ansible-test sanity.

Mandatory Imports and Metaclass

All plugin files must start with the following lines to ensure Python 2/3 compatibility and consistent class behavior:

from __future__ import absolute_import, annotations, division, print_function

__metaclass__ = type

Sources: dev/constitution.md:16-20, plugins/AGENTS.md:12-18

Infrahub SDK Guard

Because the infrahub-sdk is a runtime dependency, all plugins must use a conditional import pattern. This allows ansible-doc and sanity tests to parse the files even if the SDK is not installed in the testing environment.

try:
    from infrahub_sdk import InfrahubClientSync
    # ... other SDK imports ...
    HAS_INFRAHUBCLIENT = True
except ImportError:
    HAS_INFRAHUBCLIENT = False

The plugin must then check HAS_INFRAHUBCLIENT at runtime and fail gracefully if it is False.
Sources: dev/constitution.md:58-62, plugins/AGENTS.md:54-65

Standard Argument Specification (INFRAHUB_ARG_SPEC)

The INFRAHUB_ARG_SPEC dictionary defines the standard set of arguments used to connect to an Infrahub instance.

Core Connection Parameters

This specification is centrally defined in plugins/module_utils/infrahub_utils.py.

Parameter	Type	Required	Default	Description
api_endpoint	str	True	None	URL of the Infrahub API. Falls back to INFRAHUB_ADDRESS environment variable.
token	str	True	None	API token for authentication. Falls back to INFRAHUB_API_TOKEN. no_log is set to True.
state	str	False	present	Desired state of the object (present or absent).
validate_certs	bool	False	True	Whether to validate SSL certificates.
timeout	int	False	10	Timeout for API requests in seconds.

Sources: plugins/module_utils/infrahub_utils.py:102-113, dev/knowledge/plugin-patterns.md, plugins/AGENTS.md:43-52

Argument Spec Extension Pattern

When creating a new module, developers must not modify the global INFRAHUB_ARG_SPEC. Instead, they use a deepcopy pattern to inherit standard arguments and append module-specific parameters.

This diagram shows the standard flow for initializing a module's argument specification.
Sources: dev/knowledge/plugin-patterns.md, dev/knowledge/processors-and-arg-spec.md

Documentation Fragments

To maintain consistency in user-facing documentation, the collection uses doc_fragments. These fragments allow multiple modules to share the same parameter descriptions without manual duplication.

ModuleDocFragment Class

Shared blocks are defined in plugins/doc_fragments/fragments.py. The BASE fragment contains the documentation for all core connection parameters defined in INFRAHUB_ARG_SPEC.

Fragment Name	Description
BASE	Documentation for api_endpoint, token, timeout, branch, and validate_certs.
TAGS	Standard documentation for handling object tags.

Sources: plugins/doc_fragments/fragments.py:13-39, dev/constitution.md:23-25

SDK Wrapper and Client Initialization

All modules and action plugins must use the InfrahubclientWrapper rather than calling the SDK's InfrahubClientSync directly. This wrapper handles standard configuration and logging.

This sequence shows the mandatory abstraction layer between the Ansible module and the raw SDK.
Sources: dev/constitution.md:55-57, plugins/module_utils/infrahub_utils.py:116-160

Summary of Implementation Rules

• Metaclass: Always include __metaclass__ = type.
• Future Imports: Always include the four standard from __future__ imports.
• Security: Always set no_log: True for the token parameter.
• Environment: Always provide environment variable fallbacks for connection details.
• State: Modules managing objects must support state: present and state: absent.

Sources: dev/constitution.md:15-85, plugins/AGENTS.md:90-105

Standardizing argument specs and boilerplate ensures that the opsmill.infrahub collection remains maintainable and that all plugins provide a predictable experience for end-users, regardless of the specific task being performed.