Dynamic Inventory Plugin

Relevant source files

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

• plugins/inventory/inventory.py
• dev/knowledge/inventory-and-lookup.md
• plugins/module_utils/infrahub_utils.py
• specs/001-inventory-fetch-performance/spec.md
• specs/001-inventory-fetch-performance/contracts/inventory-options.md
• plugins/AGENTS.md
• dev/knowledge/plugin-patterns.md

The Dynamic Inventory Plugin generates an Ansible inventory by fetching infrastructure data from Infrahub. It translates Infrahub nodes into Ansible hosts and organizes them based on user-defined node types, attributes, and relationships.

This plugin allows automation engineers to work with real-time infrastructure data. It supports advanced features such as attribute selection, branch-aware fetches, and performance optimizations like batched peer fetching and result caching.

Architecture and Design

The plugin follows a multi-layered architecture where the inventory entry point delegates complex data fetching and processing logic to shared utility classes.

Component Overview

Component	Responsibility
InventoryModule	Inherits from BaseInventoryPlugin, Constructable, and Cacheable. It handles Ansible plugin lifecycle and configuration parsing.
InfrahubclientWrapper	Manages the connection to the Infrahub API, handling authentication, branch selection, and timeouts.
InfrahubNodesProcessor	Orchestrates the retrieval of nodes, handling pagination, relationship resolution, and peer warming.
HostFetch	A data structure that tracks the state of a fetch operation, including projections, loaded nodes, and failures.

Sources: dev/knowledge/inventory-and-lookup.md, plugins/inventory/inventory.py:27-29, specs/001-inventory-fetch-performance/plan.md

Data Flow

The following diagram illustrates the sequence of operations when Ansible invokes the inventory plugin.

Configuration and Parameters

The plugin is configured via a YAML file (e.g., inventory.infrahub.yml). It uses standard connection parameters alongside specific Infrahub selection logic.

Connection Options

Parameter	Type	Default	Description
api_endpoint	string	None	Infrahub API URL. Can be set via INFRAHUB_ADDRESS.
token	string	None	API Token. Can be set via INFRAHUB_API_TOKEN.
branch	string	"main"	The Infrahub branch to query.
timeout	integer	60	Request timeout in seconds.
validate_certs	boolean	True	Whether to validate SSL certificates.

Sources: plugins/inventory/inventory.py:32-68, specs/001-inventory-fetch-performance/contracts/inventory-options.md

Node Selection (Input Contract)

Users define which Infrahub nodes to include using the nodes key. Each node type (kind) can specify an attribute selection.

nodes:
  InfraDevice:
    include:
      - name
      - platform.ansible_network_os
      - primary_address.address
      - site.name
    filters:
      status: {value: "active"}

Sources: specs/001-inventory-fetch-performance/contracts/inventory-options.md, dev/knowledge/inventory-and-lookup.md

Performance Optimizations

To handle large estates, the plugin implements several fetch performance improvements.

Query Projection and Batching

1. Attribute Selection (Projections): The system requests only the identifiers and attributes defined in the include block. If no selection is provided, it defaults to a full attribute fetch.
2. Batched Peer Fetching: Instead of fetching related nodes one by one, the plugin collects all referenced IDs and fetches them in batches.
3. Refill Mechanism: If a relationship uses a broad type (e.g., "Location") but the user requests an attribute specific to a subtype (e.g., "Site Name"), the plugin performs a targeted "refill" fetch for those specific nodes.

Sources: specs/001-inventory-fetch-performance/spec.md:FR-001-FR-010, specs/001-inventory-fetch-performance/plan.md

Caching Strategy

The plugin uses Ansible's caching interface to persist results. Cache keys are unique to prevent collisions between different environments.

Diagnostics and Reporting

The plugin provides diagnostic information based on Ansible's verbosity levels.

• Default Verbosity: The plugin is silent, reporting only critical errors.
• Raised Verbosity (-v): The plugin reports the number of requests sent to Infrahub, the number of nodes loaded beyond hosts, and the number of batches processed.
• Error Handling:
  • If a specific node type fails to load, the plugin issues a warning and skips that type.
  • If a related node batch fails, referencing hosts are still produced with empty attributes for those fields.
  • If all selected node types fail, the run fails with a descriptive error.

Sources: specs/001-inventory-fetch-performance/spec.md:FR-014-FR-020, specs/001-inventory-fetch-performance/contracts/inventory-options.md

Conclusion

The Dynamic Inventory Plugin serves as a high-performance bridge between Infrahub and Ansible. By utilizing efficient fetching patterns such as query projection and batched peer resolution, it minimizes API round-trips and reduces wall-clock time for inventory generation. Its integration with Ansible's native caching and diagnostic systems ensures it is both reliable and easy to troubleshoot in complex infrastructure environments.