Automate Engine & State Machines
Relevant source files
The following files were used as context for generating this wiki page:
The Automate Engine is a core component of ManageIQ designed to provide a highly flexible automation framework for IT processes, provisioning, and policy-based management. It allows users to define custom logic using Domains, Namespaces, Classes, and Methods, which can be instantiated to execute complex workflows.
State Machines within the Automate Engine represent a specialized type of Automate Class where fields are defined as "states." These machines manage transitions between discrete steps of a task, handling retries, timeouts, and error conditions automatically. This system is heavily integrated with the internal messaging queue and request task system to ensure reliable execution across different management zones.
Core Components of the Automate Engine
The Automate Engine uses a hierarchical structure to organize automation logic. This hierarchy ensures that logic can be overridden and extended without modifying the base system.
Hierarchy and Object Model
Logic is organized from top to bottom as follows:
- Domains: The highest level of organization. Priority-ordered domains allow users to shadow base logic with custom implementations.
- Namespaces: Logical groupings within a domain to categorize classes.
- Classes: Definitions of automation objects, including their schema (fields), instances, and methods.
- Methods: The actual executable logic, often written in Ruby or Perl.
The engine resolves objects by searching through enabled domains in descending priority order.
Sources: app/models/miq_ae_class.rb, app/models/miq_ae_method.rb:45-47
Automate Methods
Automate Methods support various locations and languages. While Ruby is the primary language for inline scripts, methods can also represent expressions or Ansible-based tasks.
| Location | Description |
|---|---|
builtin | Logic hardcoded within the ManageIQ engine. |
inline | User-defined Ruby scripts executed within the engine context. |
expression | Logic defined using the ManageIQ expression parser. |
playbook | Integration with Ansible Playbooks. |
ansible_job_template | Execution of pre-defined Ansible Tower job templates. |
Sources: app/models/miq_ae_method.rb:23-25, app/models/miq_ae_method.rb:39-43
State Machine Architecture
State Machines are defined by an MiqAeClass that contains fields with the aetype of state. The state_machine? method checks for the presence of at least one state-type field in the class schema.
The diagram above illustrates the typical lifecycle of a state machine execution where results determine if the machine advances or retries.
Sources: app/models/miq_ae_class.rb:147-151, app/models/miq_request_task.rb:167-175
State Field Attributes
Fields in a State Machine schema control how the state behaves during execution:
- Method: The automation method to execute for this state.
- On Entry: Logic to execute before the main method.
- On Exit: Logic to execute after the main method.
- On Error: Error handling logic if the method fails.
- Max Retries: Limit on how many times a state can be retried.
Sources: app/models/miq_ae_class.rb:147-160, spec/support/automation_helper.rb:25-30
Request and Task Integration
Automate is frequently triggered via MiqRequest and MiqRequestTask objects. When a request is approved, it delivers an automation task to the engine.
Task Delivery Flow
The delivery process involves checking for approval and then placing a message on the MiqQueue for the MiqAeEngine.
Provisioning Automation
Automation is used extensively during VM and service provisioning to determine placements, names, and network details. Methods like get_placement_via_automate resolve suitable hosts, clusters, and storage by calling specific automation entry points.
Sources: app/models/miq_provision/automate.rb:20-28, app/models/miq_provision/automate.rb:43-52
Automate Actions and Events
The system allows policy-based events to trigger automation through MiqAction.
Custom Automation Actions
An action of type custom_automation can be configured to call the Automate Engine with specific attributes and a starting instance (usually REQUEST).
| Action Field | Description |
|---|---|
ae_request | The starting request string for the Automate Engine. |
ae_attributes | A hash of key-value pairs passed as arguments to the engine. |
ae_message | The message to send to the automation object (default is create). |
Sources: app/models/miq_action.rb:449-467, app/models/miq_action.rb:24-34
Summary
The Automate Engine and its State Machines provide the underlying logic for virtually all complex operations in the platform. By leveraging a priority-based Domain model and a robust State Machine schema, the system allows for both standardized workflows (like provisioning) and highly customized user-defined automation. Integration with MiqQueue and MiqRequestTask ensures that these operations are performed asynchronously and reliably across distributed environments.