GraphQL Query Module

Relevant source files

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

• plugins/modules/query_graphql.py
• dev/knowledge/architecture.md
• dev/knowledge/plugin-patterns.md
• dev/constitution.md
• plugins/AGENTS.md
• dev/guides/creating-a-module.md

The query_graphql module executes GraphQL queries against an Infrahub instance. It allows users to retrieve specific infrastructure data by passing GraphQL query strings and variables directly from Ansible playbooks. Sources: plugins/modules/query_graphql.py:12-16, dev/knowledge/architecture.md:46-47

This module forms part of the project's read-only operations. It does not manage state or ensure idempotency, as it primarily serves to fetch data for use in subsequent tasks or for populating host variables. Sources: dev/constitution.md:32-33, plugins/modules/query_graphql.py:54-58

Architecture and Design

The query_graphql module implements the Action Plugin Pattern. In this architecture, the module file located in plugins/modules/ acts as a stub containing documentation and argument specifications. The actual execution logic resides in a corresponding action plugin on the Ansible controller. Sources: dev/constitution.md:27-31, dev/knowledge/architecture.md:38-42, dev/guides/creating-a-module.md:12-15

Component Responsibilities

• Module Stub (query_graphql.py): Defines the DOCUMENTATION, EXAMPLES, and RETURN strings. It validates input arguments using the AnsibleModule constructor but does not execute API calls. Sources: plugins/modules/query_graphql.py:12-90, dev/knowledge/architecture.md:33-37
• Action Plugin: Inherits from ActionBase. It initializes the SDK client, handles credentials, and performs the GraphQL request on the controller side. Sources: dev/knowledge/architecture.md:43-45, dev/knowledge/plugin-patterns.md:73-81
• InfrahubclientWrapper: Mediates all API access. It abstracts the InfrahubClientSync from the infrahub-sdk to provide a consistent interface for executing queries. Sources: dev/constitution.md:54-55, dev/knowledge/architecture.md:104-106

Data Flow

The following diagram illustrates the execution flow when a playbook task calls the query_graphql module.

The diagram shows the synchronous request-response cycle mediated by the Action Plugin on the Ansible controller. Sources: dev/knowledge/architecture.md:92-96, dev/knowledge/plugin-patterns.md:82-95

Module Parameters

The module accepts several parameters to configure the connection and the specific query.

Parameter	Type	Required	Default	Description
api_endpoint	str	No	None	Endpoint of the Infrahub API. Falls back to INFRAHUB_ADDRESS.
token	str	No	None	API token. Falls back to INFRAHUB_API_TOKEN. Set to no_log: True.
query	str	Yes	-	GraphQL query parameters or filters to send to Infrahub.
graph_variables	dict	No	{}	Dictionary of keys/values to pass into the GraphQL query.
branch	str	No	main	The Infrahub branch context for the request.
timeout	int	No	10	Timeout for Infrahub requests in seconds.
validate_certs	bool	No	True	Whether to validate SSL certificates.
update_hostvars	bool	No	False	Whether to populate results directly into root hostvars.

Sources: plugins/modules/query_graphql.py:20-61, dev/knowledge/plugin-patterns.md:46-48

Implementation Details

Credential Handling

The module prioritizes credentials passed in task arguments. If arguments are missing, it falls back to environment variables INFRAHUB_ADDRESS and INFRAHUB_API_TOKEN. Token parameters are protected with no_log=True to prevent exposure in logs. Sources: dev/constitution.md:65-68, dev/knowledge/plugin-patterns.md:89-92

SDK Integration

The module requires the infrahub-sdk Python package. It uses a conditional import pattern to ensure ansible-doc can parse the file even if the SDK is not installed on the system performing the parsing. Sources: dev/constitution.md:58-61, dev/knowledge/plugin-patterns.md:104-110

try:
    from infrahub_sdk import InfrahubClientSync
    HAS_INFRAHUBCLIENT = True
except ImportError:
    HAS_INFRAHUBCLIENT = False

Sources: dev/knowledge/plugin-patterns.md:104-110, plugins/AGENTS.md:44-50

Host Variable Integration

When update_hostvars is set to True, the module places the query results in the root of the task response. This allows keys provided by the GraphQL query to overwrite existing keys. Users are encouraged to use GraphQL aliases to prevent accidental variable overwriting. Sources: plugins/modules/query_graphql.py:54-61

Conclusion

The GraphQL Query Module provides a flexible interface for retrieving data from Infrahub. By utilizing the Action Plugin pattern, it ensures that high-performance GraphQL operations are handled directly on the controller using the Infrahub SDK. This architecture maintains compliance with Ansible collection standards while providing efficient access to the Infrahub infrastructure data platform. Sources: dev/knowledge/architecture.md:46-49, dev/constitution.md:10-15