GraphQL Lookup Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The GraphQL Lookup Plugin enables users to execute inline GraphQL queries against the Infrahub API directly within Ansible playbooks. It retrieves infrastructure data dynamically during playbook execution by interacting with the Infrahub Architecture. This plugin serves as a read-only interface for querying the Infrahub database without requiring dedicated state-management modules.
The plugin utilizes a specialized processor class to execute queries and extract results. It integrates with the standard Infrahub authentication and connection parameters, supporting both direct arguments and environment variable fallbacks.
Sources: dev/knowledge/architecture.md:52-59, dev/knowledge/inventory-and-lookup.md
Architecture and Data Flow
The Lookup Plugin follows the standard Ansible lookup plugin pattern, inheriting from LookupBase. It acts as a bridge between the Ansible controller and the Infrahub SDK.
Interaction Flow
When a lookup is called in a Jinja2 template or a task, the plugin initializes an InfrahubclientWrapper to manage the session. It then passes the GraphQL query string and variables to the InfrahubQueryProcessor, which executes the query via the SDK's synchronous client.
The data flow ensures that complex GraphQL queries are handled by a dedicated processor to maintain consistency with other plugins in the collection.
Sources: dev/knowledge/architecture.md:83-87, plugins/lookup/lookup.py
Plugin Components
The plugin relies on several key classes and utilities within the opsmill.infrahub collection to perform its duties.
Key Classes
| Component | Description |
|---|---|
LookupModule | The primary entry point that implements the run() method required by Ansible. |
InfrahubclientWrapper | Manages connection settings, authentication tokens, and the underlying SDK client instance. |
InfrahubQueryProcessor | Handles the execution logic for GraphQL queries and formats the returned data. |
Sources: dev/knowledge/architecture.md:104-118, plugins/lookup/lookup.py
Execution Logic
The plugin's run method performs the following sequence:
- Validates that
infrahub-sdkis installed using theHAS_INFRAHUBCLIENTguard. - Extracts connection parameters (URL, Token, Branch) from arguments or environment variables.
- Instantiates the
InfrahubclientWrapper. - Passes the
queryandgraph_variablesto theInfrahubQueryProcessor.query()method. - Returns a list of results to the Ansible engine.
Sources: plugins/lookup/lookup.py, dev/knowledge/plugin-patterns.md:108-115
Configuration and Parameters
The lookup plugin accepts parameters both as inline key-value pairs and through standard Infrahub environment variables.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | str | Yes | N/A | The GraphQL query string to execute. |
graph_variables | dict | No | {} | Variables to pass along with the GraphQL query. |
api_endpoint | str | No | INFRAHUB_ADDRESS | The URL of the Infrahub instance. |
token | str | No | INFRAHUB_API_TOKEN | Authentication token for the API. |
branch | str | No | main | The Infrahub branch to query against. |
timeout | int | No | 10 | Request timeout in seconds. |
validate_certs | bool | No | True | Whether to verify SSL certificates. |
Sources: plugins/lookup/lookup.py, dev/knowledge/plugin-patterns.md:32-44
Usage Example
Users invoke the plugin using the query or lookup keywords in Ansible.
- name: Fetch data using GraphQL lookup
set_fact:
nodes: "{{ query('opsmill.infrahub.lookup', query=my_graphql_query, graph_variables={'status': 'active'}) }}"
In this example, the plugin executes the query stored in my_graphql_query, passing the status variable to Infrahub. The result is returned as a list and stored in the nodes fact.
Sources: dev/knowledge/architecture.md:55-58, plugins/lookup/lookup.py
Implementation Details
The lookup plugin follows the "Action Plugin" style logic where it executes entirely on the controller. It requires the infrahub-sdk Python package to be present on the control node.
Error Handling
The plugin uses the handle_infrahub_exceptions_decorator (from module_utils/exception.py) to map SDK-specific errors into standard Ansible errors. If the API is unreachable or the GraphQL query is malformed, the plugin raises an AnsibleError with a descriptive message.
Sources: dev/knowledge/architecture.md:112-114, dev/knowledge/plugin-patterns.md:149-155
SDK Dependency Guard
To ensure the collection can be inspected by ansible-doc even without dependencies, the plugin implements a conditional import pattern.
try:
from infrahub_sdk import InfrahubClientSync
HAS_INFRAHUBCLIENT = True
except ImportError:
HAS_INFRAHUBCLIENT = False
If HAS_INFRAHUBCLIENT is False at runtime, the plugin calls module.fail_json or raises an AnsibleError.
Sources: dev/knowledge/plugin-patterns.md:120-134, AGENTS.md:95-99
Summary
The GraphQL Lookup Plugin provides a flexible way to retrieve dynamic data from Infrahub during a playbook run. By leveraging the InfrahubQueryProcessor and InfrahubclientWrapper, it maintains architectural consistency with the rest of the opsmill.infrahub collection while offering a simplified read-only interface for GraphQL interactions.