MiqPolicy Engine & Profiles
Relevant source files
The following files were used as context for generating this wiki page:
The MiqPolicy Engine is a core component of ManageIQ designed to provide automated control and compliance across various managed entities. It allows administrators to define rules (Policies) consisting of conditions that, when met or failed during specific events, trigger defined actions. Policies are organized into Policy Profiles (represented by the MiqPolicySet model) which are then assigned to targets such as Virtual Machines, Hosts, or Containers.
Sources: app/models/miq_policy.rb:3-5, app/models/miq_policy_set.rb:1-5
Core Architecture & Components
The policy system is built on a relational structure where policies act as containers for logic tied to specific events and actions.
Component Relationships
The following ER diagram illustrates the primary entities within the policy engine and how they relate to one another:
The MiqPolicyContent model acts as a join table that binds a policy to a specific event and the actions to be taken for that event.
Sources: app/models/miq_policy.rb:45-50, app/models/miq_policy_content.rb:1-5, app/models/miq_policy_set.rb:4-5
Policy Targets (Towhat)
Policies are typed based on the resource they govern. The towhat attribute determines which class of object the policy applies to.
| Supported Target Classes | Description |
|---|---|
| Vm | Virtual Machines and Instances |
| Host | Physical Hosts |
| ContainerGroup | Kubernetes Pods / OpenShift Groups |
| ContainerImage | Container Images |
| ExtManagementSystem | Providers / Management Systems |
| PhysicalServer | Physical Hardware Servers |
Sources: app/models/miq_policy.rb:8-16
Policy Execution & Enforcement
The MiqPolicy.enforce_policy method is the entry point for evaluating policies against a target. Enforcement follows a distinct workflow depending on the policy mode: Control or Compliance.
Enforcement Workflow
- Event Trigger: An event is received (e.g., VM Start, Compliance Check).
- Policy Retrieval: The engine gathers all policy profiles assigned to the target and its parents (EMS, Cluster, Host).
- Condition Evaluation: Conditions within the applicable policies are checked using the
MiqExpressionengine. - Action Invocation: Based on success or failure, synchronous or asynchronous actions are triggered.
Policy Modes
Policies operate in one of two modes defined in the system:
| Mode | Logic | Behavior |
|---|---|---|
| Control | Event-driven | Triggers actions immediately upon event detection and condition result. |
| Compliance | State-driven | Typically invoked during scheduled checks to verify if a resource meets requirements. |
Sources: app/models/miq_policy.rb:24-27
MiqAction System
Actions are the executable consequences of policy evaluation. They can be performed synchronously (immediately) or asynchronously (via the MiqQueue).
Common Action Types
The MiqAction model defines several built-in types:
- Email: Sends notifications using
GenericMailer. - SNMP Trap: Sends alerts to external monitoring systems.
- Tagging: Applies or removes ManageIQ tags (Classifications).
- VM Control: Start, Stop, Suspend, Clone, or Snapshot VMs.
- Automation: Invokes custom Ruby methods or Ansible Playbooks.
- Audit: Records success or failure in the audit log.
Sources: app/models/miq_action.rb:11-25, app/models/miq_action.rb:211-230
Action Invocation Logic
When MiqAction.invoke_actions is called, it processes two lists: succeeded policies and failed policies. Actions for successful results are run first, followed by actions for failures. The prevent action is specialized; it defers processing to stop the current operation if a policy check fails.
Sources: app/models/miq_action.rb:108-165
Resultant Set of Policy (RSOP)
ManageIQ provides a mechanism to simulate policy enforcement without actually executing actions, known as RSOP. This is used for troubleshooting and planning to see which policies would apply to a target for a given event.
RSOP Process
- Asynchronous Execution: RSOP can be run via
rsop_async, which creates anMiqTaskand queues the calculation. - Resolution: It uses
MiqPolicy.resolveto walk through conditions and record the "virtual" results.
Sources: app/models/mixins/miq_policy_mixin.rb:110-141, app/models/miq_policy.rb:271-291
Policy Profiles (MiqPolicySet)
Policy Profiles are the administrative unit for assignment.
- Membership: A profile contains multiple policies via
acts_as_miq_set. - Assignment: Targets do not have individual policies assigned; instead, they have tags representing Policy Profile assignments (e.g.,
/miq_policy/assignment/miq_policy_set/123). - Inheritance: The policy engine automatically checks parents for assigned profiles (e.g., a VM inherits profiles assigned to its Host).
Sources: app/models/miq_policy_set.rb:1-10, app/models/mixins/miq_policy_mixin.rb:8-25, app/models/miq_policy.rb:397-410
Conclusion
The MiqPolicy Engine provides a robust, event-driven framework for governance. By decoupling the trigger (Event), the logic (Condition), and the result (Action), ManageIQ enables complex automation scenarios ranging from simple compliance reporting to complex lifecycle management (e.g., preventing retired instances from starting). The engine's ability to aggregate policies from multiple levels of the infrastructure hierarchy ensures that enterprise-wide standards are enforced consistently across the environment.