Schema Management Module

Relevant source files

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

• plugins/modules/schema.py
• plugins/module_utils/schema.py
• plugins/module_utils/infrahub_utils.py
• tests/integration/targets/playbooks/schema.yml
• dev/guides/creating-a-module.md
• plugins/AGENTS.md

The Schema Management Module manages Infrahub schemas through the Infrahub SDK. It provides functionality to load new schema definitions, check the validity of existing definitions without applying changes, and export currently active schemas from the Infrahub instance.

Sources: plugins/modules/schema.py:12-16, plugins/module_utils/schema.py

Architecture and Components

The module follows the "Module Utils" pattern, where a thin module stub delegates execution logic to a specialized class.

Component Breakdown

Component	File Path	Role
Module Stub	plugins/modules/schema.py	Defines the Ansible interface, argument specifications, and documentation.
Logic Handler	plugins/module_utils/schema.py	Implements SchemaModule, which inherits from InfrahubModule to execute SDK calls.
SDK Wrapper	plugins/module_utils/infrahub_utils.py	Provides InfrahubclientWrapper for mediated API access.

Sources: plugins/modules/schema.py:161-177, plugins/module_utils/schema.py, plugins/AGENTS.md:52, dev/guides/creating-a-module.md:104-121

Execution Flow

The following diagram illustrates the interaction between the Ansible task, the module stub, and the underlying SDK logic.

The workflow begins with the user defining a task in a playbook, which triggers the module stub to validate inputs before passing control to the SchemaModule logic handler.
Sources: plugins/modules/schema.py:173-177, plugins/module_utils/schema.py, dev/guides/creating-a-module.md:115-121

Operations and Actions

The module supports three distinct actions specified via the action parameter.

1. Load Action

Loads schema definitions into Infrahub. You can provide definitions as inline dictionaries via the schemas parameter or as file paths via schema_files. It supports an optional wait_until_converged flag to ensure synchronization across all workers.
Sources: plugins/modules/schema.py:18-20, plugins/modules/schema.py:68-72

2. Check Action

Validates schema definitions without applying them to the Infrahub instance. This is used to verify syntax and logic before deployment.
Sources: plugins/modules/schema.py:21, tests/integration/targets/playbooks/schema.yml:23-28

3. Export Action

Retrieves existing schemas from Infrahub. You can filter the export by providing a list of namespaces.
Sources: plugins/modules/schema.py:22, plugins/modules/schema.py:63-67

Configuration Options

The module utilizes a combination of standard Infrahub parameters and schema-specific options.

Parameter	Type	Required	Default	Description
action	str	Yes	N/A	The action to perform: load, check, or export.
schemas	list	No	N/A	List of inline schema definitions (dict).
schema_files	list	No	N/A	List of YAML file paths containing schema definitions.
namespaces	list	No	N/A	Namespace names to filter exports.
wait_until_converged	bool	No	False	Wait for schema synchronization across workers.
api_endpoint	str	No	env: INFRAHUB_ADDRESS	Infrahub API endpoint.
token	str	No	env: INFRAHUB_API_TOKEN	API token for authentication.
branch	str	No	main	Branch for the request.

Sources: plugins/modules/schema.py:32-72, plugins/modules/schema.py:165-172, plugins/AGENTS.md:41-47

Module Returns

The module returns specific data based on the action performed.

# Example Return for action=load
changed: true
schema_updated: true
hash: "a1b2c3d4..."
previous_hash: "e5f6g7h8..."
msg: "Schema loaded successfully"

# Example Return for action=export
schemas:
  Testing:
    nodes:
      - name: Sandwich
        namespace: Testing
        ...

Sources: plugins/modules/schema.py:112-152, tests/integration/targets/playbooks/schema.yml:61-75

Detailed Return Values

Key	Action	Type	Description
changed	All	bool	Indicates if the schema was updated (always false for check/export).
valid	check	bool	Whether the schema passed validation.
errors	check	dict	Validation errors if the check fails.
hash	load	str	New schema hash after loading.
schemas	export	dict	Exported schemas organized by namespace.

Sources: plugins/modules/schema.py:112-152

Implementation Example

The following YAML snippet demonstrates a typical integration test flow involving checking, loading, and filtering an export.

- name: Load schema from inline definition
  opsmill.infrahub.schema:
    action: load
    schemas:
      - version: "1.0"
        nodes:
          - namespace: "Testing"
            name: "Sandwich"
            attributes:
              - name: "name"
                kind: "Text"
                unique: true
  register: load_result

- name: Export schemas for specific namespaces
  opsmill.infrahub.schema:
    action: export
    namespaces:
      - Testing
  register: export_filtered

Sources: tests/integration/targets/playbooks/schema.yml:10-21, tests/integration/targets/playbooks/schema.yml:68-75

Conclusion

The Schema Management Module provides a centralized interface for schema lifecycle operations in Infrahub. By separating logic into the SchemaModule class and utilizing the shared InfrahubclientWrapper, the module ensures consistent API interaction while supporting complex workflows like convergence waiting and namespace-filtered exports.

Sources: plugins/modules/schema.py, plugins/module_utils/schema.py, plugins/module_utils/infrahub_utils.py