Infrahub SDK Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub SDK Integration provides a standardized interface for Ansible plugins to interact with the Infrahub infrastructure data platform. This system abstracts the underlying infrahub-sdk Python package, ensuring consistent credential handling, synchronous execution, and unified error mapping across all modules, action plugins, and inventory sources.
Central to this integration is the InfrahubclientWrapper, which acts as the sole gateway for API access. This architecture prevents direct coupling between individual Ansible plugins and the raw SDK, allowing for centralized updates and more robust testing through mocking.
Sources: dev/adr/0002-sdk-abstraction-wrapper.md:1-24, dev/knowledge/architecture.md:73-81
Core Abstraction Layer
The InfrahubclientWrapper class in plugins/module_utils/infrahub_utils.py manages the lifecycle of the SDK client. It handles the instantiation of InfrahubClientSync using a provided Config object that includes connection details like the API endpoint, token, and branch.
Client Wrapper Architecture
The diagram shows how various components utilize the wrapper to reach the SDK.
Sources: dev/adr/0002-sdk-abstraction-wrapper.md:15-32, dev/knowledge/infrahub-sdk-usage.md:12-25, dev/knowledge/architecture.md:83-99
Synchronous Execution Requirement
Ansible operates in a synchronous execution context. Consequently, this collection exclusively uses the synchronous SDK client (InfrahubClientSync). The project constitution strictly forbids the use of async SDK methods to maintain compatibility with Ansible's execution model.
Sources: dev/constitution.md:130-131, dev/knowledge/infrahub-sdk-usage.md:31-33
Integration Patterns and Boilerplate
All plugins must follow specific patterns to ensure the collection remains portable and passes Ansible sanity tests.
Conditional Import Pattern
To allow ansible-doc and sanity tests to parse files without the SDK installed, every file interacting with the SDK must use a try/except block for imports. A boolean flag HAS_INFRAHUBCLIENT is defined based on the success of these imports.
try:
from infrahub_sdk import InfrahubClientSync
HAS_INFRAHUBCLIENT = True
except ImportError:
HAS_INFRAHUBCLIENT = False
Sources: dev/knowledge/plugin-patterns.md:118-133, plugins/AGENTS.md:52-64
Data Flow and Credentials
Plugins derive credentials from module arguments or environment variable fallbacks. The following table details the standard configuration options provided via INFRAHUB_ARG_SPEC.
| Parameter | Type | Default | Env Fallback | Description |
|---|---|---|---|---|
api_endpoint | string | None | INFRAHUB_ADDRESS | Endpoint of the Infrahub API |
token | string | None | INFRAHUB_API_TOKEN | API token (marked no_log=True) |
timeout | integer | 10 | None | Request timeout in seconds |
branch | string | "main" | None | Target Infrahub branch |
validate_certs | boolean | True | None | Validates SSL certificates |
Sources: plugins/AGENTS.md:40-50, dev/knowledge/infrahub-sdk-usage.md:113-118, dev/knowledge/infrahub-sdk-usage.md:195-201
Exception Mapping
The integration utilizes a decorator-based approach to map SDK-specific exceptions to user-friendly Ansible error messages. This prevents SDK internals from leaking into the Ansible user interface.
The flow shows the mapping logic handled by the exception decorator.
| SDK Exception | Ansible Handling |
|---|---|
GraphQLError | Parses specific GraphQL error strings |
SchemaNotFoundError | Reports missing Kind in Infrahub schema |
BranchNotFoundError | Reports invalid branch name |
ServerNotReachableError | Reports connectivity issues |
Sources: dev/knowledge/infrahub-sdk-usage.md:180-193, dev/constitution.md:65-67
High-Level Orchestration
Beyond raw API calls, the integration provides processor classes for complex operations, particularly for dynamic inventory and GraphQL lookups.
Processor Classes
- InfrahubNodesProcessor: Used by the dynamic inventory plugin to fetch nodes, resolve relationships, and transform them into host variables.
- InfrahubQueryProcessor: Used by lookup plugins and GraphQL actions to execute and process raw queries.
- InfrahubModule: The base class for stateful CRUD modules (like
nodeorbranch). It manages idempotency via the "fetch-compare-act" cycle.
Sources: dev/knowledge/infrahub-sdk-usage.md:154-178, dev/knowledge/architecture.md:95-99
Relationship Resolution
The InfrahubNodesProcessor handles complex relationship pre-fetching. For performance efficiency, the integration translates user-defined selections into SDK exclude lists, as the SDK include parameter does not natively narrow top-level query results.
Sources: dev/knowledge/infrahub-sdk-usage.md:209-216, specs/001-inventory-fetch-performance/plan.md:15-28
Conclusion
Infrahub SDK Integration ensures that the opsmill.infrahub collection interacts with the Infrahub API in a consistent, secure, and performant manner. By enforcing the use of InfrahubclientWrapper, the project maintains a clear boundary between Ansible logic and the SDK, facilitating easier maintenance and ensuring that all operations remain idempotent and synchronous.