Introduction to opsmill.infrahub

Relevant source files

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

• README.md
• AGENTS.md
• dev/README.md
• dev/constitution.md
• dev/knowledge/architecture.md
• plugins/AGENTS.md
• dev/knowledge/plugin-patterns.md
• dev/guidelines/documentation.md

The opsmill.infrahub Ansible collection provides a suite of modules, plugins, and inventory sources to interact with the Infrahub infrastructure data platform. This collection enables users to manage infrastructure data programmatically through Ansible playbooks, supporting operations such as node CRUD (Create, Read, Update, Delete), branch management, and GraphQL queries.

Sources: AGENTS.md:3-5, dev/knowledge/architecture.md:3-5

Collection Architecture and Layout

The collection follows a standard Ansible structure with specific internal abstractions to handle Infrahub's API. Logic is partitioned between user-facing stubs and shared utility classes that interface with the Infrahub SDK.

Directory Structure

Directory	Content Purpose
plugins/modules/	User-facing module stubs containing documentation and argument specs.
plugins/action/	Action plugins containing controller-side execution logic for API calls.
plugins/module_utils/	Shared Python utilities, including the SDK wrapper and base classes.
plugins/inventory/	Dynamic inventory plugin for fetching hosts from Infrahub.
plugins/lookup/	Lookup plugin for executing inline GraphQL queries.
docs/	Docusaurus-based documentation site source.
tests/	Multi-tier test suite (Sanity, Unit, Integration).

Sources: dev/knowledge/architecture.md:7-17, plugins/AGENTS.md:7-15

Component Relationship

The following diagram illustrates how different plugin types interact with the Infrahub SDK and the external API.

Core Development Principles

The project adheres to a "Constitution" that defines binding principles for all contributors. These rules ensure consistency, security, and compatibility with Ansible standards.

SDK Abstraction Layer

Every API access must go through the InfrahubclientWrapper. Direct calls to InfrahubClientSync are prohibited within modules or action plugins. The collection only supports synchronous operations using the sync-only SDK pattern.

Sources: dev/constitution.md:43-52, dev/constitution.md:104-106

Standardized Plugin Patterns

All plugins must follow one of two established patterns:

1. Module-Utils Pattern: Used for stateful CRUD operations (e.g., node, branch). It utilizes a subclass of InfrahubModule to manage idempotency, check_mode, and diff support.
2. Action Plugin Pattern: Used for read-only or non-idempotent operations (e.g., query_graphql, artifact_fetch). Execution occurs entirely on the Ansible controller.

Sources: dev/constitution.md:18-28, dev/knowledge/architecture.md:21-34

Data and Security Constraints

• Idempotency: Stateful modules must implement a fetch-compare-act cycle. Mutations only occur if the current state differs from the desired state.
• Boilerplate: Every Python plugin file requires from __future__ import ... and __metaclass__ = type to pass Ansible sanity tests.
• Secrets: All token parameters must use no_log=True and support environment variable fallbacks like INFRAHUB_API_TOKEN.

Sources: dev/constitution.md:30-41, dev/constitution.md:11-15, dev/constitution.md:53-56

Key Technical Components

InfrahubclientWrapper

This class serves as the sole gateway for API interaction. It handles:

• Client initialization with endpoint, token, and timeout.
• Exception mapping from SDK errors (e.g., GraphQLError, SchemaNotFoundError) to Ansible-friendly messages.
• Environment variable fallbacks for credentials.

Sources: dev/constitution.md:43-56, dev/knowledge/architecture.md:71-80

Standard Argument Spec

Shared connection parameters are defined in INFRAHUB_ARG_SPEC and extended by individual modules.

Parameter	Type	Required	Description
api_endpoint	str	Yes	Endpoint of the Infrahub API (Env: INFRAHUB_ADDRESS).
token	str	Yes	API token (Env: INFRAHUB_API_TOKEN).
state	str	No	Desired state: present or absent.
timeout	int	No	Request timeout in seconds (Default: 10).
validate_certs	bool	No	Whether to validate SSL certificates.

Sources: plugins/AGENTS.md:26-34, dev/knowledge/plugin-patterns.md:43-53

Execution Data Flow

The collection supports multiple paths for data processing depending on the plugin type.

Stateful CRUD Flow (Module-Utils)

Technical Requirements

To use or develop the collection, the environment must meet the following specifications:

• Python: >= 3.11, < 3.15
• ansible-core: >= 2.19.0
• infrahub-sdk: >= 1.19.0, < 2.0 (Sync support required)

Sources: AGENTS.md:11-17, pyproject.toml:9-12

Summary

The opsmill.infrahub collection provides a highly structured interface for Infrahub, strictly enforced by a project constitution. By utilizing two primary plugin patterns and a mandatory SDK wrapper, it ensures consistent behavior, security, and idempotency across all infrastructure management tasks. Contributors must maintain these patterns and use the provided invoke tasks for linting, testing, and documentation generation.