Extending ManageIQ (Plugins)
Relevant source files
The following files were used as context for generating this wiki page:
ManageIQ is designed as a modular platform where core functionality is extended through a plugin-based architecture. Plugins are implemented as Ruby on Rails Engines that integrate into the core system to provide specific features such as new UI components, API endpoints, or Infrastructure Provider integrations. This modularity allows for a decoupled development cycle where specific capabilities can be added or updated without altering the core codebase.
Sources: lib/vmdb/plugins.rb:21, lib/generators/manageiq/plugin/plugin_generator.rb:1-5
Plugin Architecture and Registration
Plugins in ManageIQ are recognized by the system if they are subclasses of Rails::Engine and implement a specific vmdb_plugin? check. The system uses a centralized manager, Vmdb::Plugins, to discover, initialize, and query all active plugins.
The Plugin Discovery Process
The system identifies active plugins by selecting all subclasses of Rails::Engine that respond affirmatively to the plugin check. These engines are then sorted by name to provide a consistent initialization order.
The diagram shows the lifecycle of plugin discovery and initialization within the ManageIQ environment.
Sources: lib/vmdb/plugins.rb:21-35
Key Plugin Attributes
When a plugin is registered, the system tracks several metadata attributes derived from the engine's configuration and the underlying Bundler environment.
| Attribute | Description | Source |
|---|---|---|
name | The class name of the Engine (e.g., ManageIQ::Providers::Vmware::Engine) | engine.name |
path | The filesystem path to the plugin's root directory | engine.root |
version | The version string, often including Git SHA or branch information | Bundler::Source |
Sources: lib/vmdb/plugins.rb:37-45, lib/vmdb/plugins.rb:133-160
Plugin Generators
ManageIQ provides automated generators to ensure plugins follow the standard structure required for seamless integration.
Generic Plugin Generator
The ManageIQ::PluginGenerator creates a standard gem-like structure that functions as a Rails Engine. It establishes the necessary configuration for CI/CD (GitHub Workflows), linting (Rubocop, Yamllint), and testing (RSpec).
Generated File Structure Highlights:
%plugin_name%.gemspec: Defines gem dependencies and metadata.lib/%plugin_path%/engine.rb: The primary entry point for Rails Engine integration.config/settings.yml: Plugin-specific configuration settings.bundler.d/: Directory for overriding or adding gem dependencies.
Sources: lib/generators/manageiq/plugin/plugin_generator.rb:27-70
Provider Plugin Generator
For extending ManageIQ to support new hardware or cloud platforms, the ManageIQ::ProviderGenerator (which inherits from the basic Plugin Generator) creates specialized scaffolding. This includes components for inventory collection and event handling.
The relationship between the base plugin generator and the specialized provider generator.
Sources: lib/generators/manageiq/provider/provider_generator.rb:3-23
Specialized Provider Components
The provider generator scaffolds specific model structures necessary for ManageIQ to interact with external management systems:
- Refresher: Logic to update the local database from the provider.
- Event Catcher: Services to monitor external events (e.g., VM power states).
- Metrics Collector: Workers to gather performance data.
- Inventory Collector/Parser/Persister: The triad used to fetch and store provider data.
Sources: lib/generators/manageiq/provider/provider_generator.rb:76-103
Content Integration
Plugins do not just provide code; they also contribute various types of content that the ManageIQ core consumes to build its automation and UI capabilities.
Content Discovery Methods
The Vmdb::Plugins manager provides helper methods to aggregate specific content types across all active plugins:
| Content Type | File Path Pattern | Purpose |
|---|---|---|
| Ansible Content | content/ansible/* | Roles and playbooks for use by Automate. |
| Automate Domains | content/automate/* | Importable Automate domains for logic workflows. |
| Systemd Units | systemd/* | Service definitions for Linux process management. |
| Dashboard Widgets | dashboard/widgets/* | UI components for the ManageIQ dashboard. |
| Server Roles | config/server_roles.csv | Definitions of available application roles. |
Sources: lib/vmdb/plugins.rb:69-120
Development Environment Setup
The ManageIQ environment provides utilities to facilitate plugin development, specifically ensuring that a plugin can run in a "standalone" fashion while linked to a core ManageIQ instance.
The ManageIQ::Environment.manageiq_plugin_setup method automates the following:
- Configuration: Ensures local encryption keys (
certs/v2_key) and database configs exist. - Dependencies: Runs
bundlerto install core and plugin-specific gems. - Database: Resets, migrates, and seeds the local development database.
- Automate: Resets Automate domains to include the plugin's contributions.
Sources: lib/manageiq/environment.rb:10-33
Summary
Extending ManageIQ through plugins relies on a rigid Rails Engine structure enforced by specialized generators. The Vmdb::Plugins singleton serves as the runtime registry, enabling the core system to dynamically discover code, models, and automation content across a distributed set of gems. By inheriting from ManageIQ::Providers, developers can leverage established scaffolding for inventory and event management, while the ManageIQ::Environment utilities maintain a consistent development workflow across disparate plugin projects.