Setup and Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Setup and Configuration defines the environment requirements, dependency constraints, and credential management for the opsmill.infrahub Ansible collection. This collection provides modules, lookup plugins, and inventory sources to interact with the Infrahub infrastructure data platform.
Correct configuration ensures that Ansible controllers can authenticate with Infrahub instances and manage infrastructure state through the Infrahub SDK. The system prioritizes secure credential handling and version compatibility across the tech stack.
Sources: AGENTS.md:3-8, dev/constitution.md:12-25
Tech Stack and System Requirements
The collection requires specific versions of Python, Ansible, and the Infrahub SDK to function correctly. Developers manage these dependencies using the uv tool.
Core Dependencies
| Component | Required Version | Source |
|---|---|---|
| Python | >=3.11, <3.15 | pyproject.toml:7 |
| ansible-core | >=2.19.0 | pyproject.toml:13 |
| infrahub-sdk | >=1.19.0, <2.0 | pyproject.toml:15 |
Development Tools
The project uses uv for dependency management and Invoke for task execution.
Sources: AGENTS.md:15-28, pyproject.toml:12-20
This diagram shows the relationship between core dependencies and the task runner used during setup.
Sources: AGENTS.md:15-28, pyproject.toml:13-26
Connectivity and Authentication
Authentication with Infrahub requires an API endpoint and a valid token. The collection supports both direct parameter input and environment variable fallbacks.
Standard Connection Parameters
Every module utilizes a standard set of arguments defined in INFRAHUB_ARG_SPEC.
| Parameter | Type | Default | Env Variable Fallback |
|---|---|---|---|
api_endpoint | str | None | INFRAHUB_ADDRESS |
token | str | None | INFRAHUB_API_TOKEN |
timeout | int | 10 | None |
branch | str | main | None |
validate_certs | bool | True | None |
Sources: plugins/AGENTS.md:35-42, dev/guides/creating-a-module.md:28-48
Security Constraints
- Token Masking: All token parameters must set
no_log=Trueto prevent credentials from appearing in Ansible logs. - SDK Wrapper: All API access must go through the
InfrahubclientWrapper. Direct instantiation of the rawInfrahubClientSyncis prohibited. - Sync Pattern: The collection uses the synchronous SDK only.
Sources: dev/constitution.md:73-86, dev/constitution.md:131-140
Plugin Architecture Setup
The collection implements two primary plugin patterns. Setup requirements vary based on the chosen pattern.
1. Module-Utils Pattern
Used for stateful CRUD operations like node and branch.
- Delegates execution to an
InfrahubModulesubclass inplugins/module_utils/. - Supports idempotency via
check_modeand--diff.
Sources: dev/constitution.md:35-40, dev/guides/creating-a-module.md:144-162
2. Action Plugin Pattern
Used for controller-side API calls like query_graphql and artifact_fetch.
- Logic resides in
plugins/action/. - The module stub in
plugins/modules/provides documentation and validation.
Sources: dev/constitution.md:41-45, dev/guides/creating-a-module.md:95-135
The sequence shows how configuration data flows from the user to the Infrahub API through the internal wrapper.
Sources: dev/guides/creating-a-module.md:95-140, dev/constitution.md:65-72
Collection Metadata
The galaxy.yml file contains the canonical configuration for the collection's identity and distribution.
- Namespace:
opsmill - Name:
infrahub - Version: Current semantic version (e.g.,
1.9.0) - Documentation URL:
https://docs.infrahub.app/ansible/
Sources: galaxy.yml:6-14, galaxy.yml:50-52
Summary
Setup and Configuration for the opsmill.infrahub collection centers on a Python 3.11+ environment with ansible-core and the infrahub-sdk. Authentication is primarily handled via INFRAHUB_ADDRESS and INFRAHUB_API_TOKEN environment variables, which the InfrahubclientWrapper consumes to provide a consistent interface for both Module-Utils and Action Plugin patterns. All configuration adheres to security principles including token masking and synchronous API execution.
Sources: dev/constitution.md:12-25, AGENTS.md:15-28