Scripting Actions in CloudForms
Real-time, bi-directional process integration for CloudForms Management Engine
Abstract
Chapter 1. CloudForms Management Engine Automation
Provisioning requires the Automation Engine server role enabled. Check your server role settings in Configure → Configuration → Server → Server Control.
1.1. Automation
CloudForms Management Engine Automate Model provides flexibility to not only change parts of the provisioning process, but also to allow you to automate other operational tasks. Below are some scenarios where CloudForms Management Engine can help accomplish these tasks.
- Intelligent Workload Management - An enterprise had a requirement that when a virtual machine has reached a High CPU Percent Ready for a specified period of time, a vMotion should occur to a more suitable host. For this reason, VMware’s Distributed Resource Scheduler (DRS) was not practical, as the CPU Ready metric could not trigger DRS. The solution was to leverage CloudForms Management Engine Control and CloudForms Management Engine Automate to drive the management of this workflow.
- Power on only during business hours - An organization which gave a group of self-service users CloudForms Management Engine access had a requirement to only allow certain virtual machines to be powered during business hours. This was solved with CloudForms Management Engine Automate.
- Auto-Tagging virtual machines based on file contents - An IT organization needed a way to consume information from a text file on a virtual machine and dynamically populate vCenter. The data used to auto-tag virtual machines is also used to align unmanaged virtual machines to the business.
Chapter 2. Automate Model
CloudForms Management Engine Automate enables real-time, bi-directional process integration. This provides users with a method to implement adaptive automation for management events and administrative or operational activities.
2.1. Automate Model
The Automate model is arranged to provide an object oriented hierarchy to control automation functions. The model uses the following organizational units arranged in a hierarchy:
- Datastore - The main organization unit that stores the entire model.
- Domains - Domains act as collection of automation functions. Functions are executed depending on the order of Domain priority, which means a function in a Domain with a higher priority overrides the same functions specified in a lower-priority Domain. This allows CloudForms Management Engine to specify a core Domain (ManageIQ) but allow users to override automate functions with custom Domains. Each Domain contains a set of Namespaces.
- Namespaces - Containers that organize and categorize functions of the model. Namespaces can contain child Namespaces as well as Classes.
- Classes - Templates for a specific function of the model. Each Class uses a Schema to apply to Instances to populate with default values. Each class also can contain a set of methods.
- Instances - An instance is a version of a class populated with initial configuration data. An instance can include a collection of any number of attributes, calls to methods, and relationships.
- Methods - Methods are functions within the model. Methods use Ruby code to execute various operations needed for a Class.
CloudForms Management Engine contains a set of preconfigured Domains for users:
ManageIQ - The core domain for CloudForms Management Engine Automate operations. This domain is locked with the following Namespaces:
- Cloud - General cloud instance lifecycle from provisioning, retirement, methods, email.
- Control - Control contains email alerts for policy controls.
- Infrastructure - General infrastructure VM lifecycle from provisioning, retirement, methods, email.
- Service - Service lifecycle from provisioning, retirement, methods, email.
- System - System contains classes that can provide the start points for all CloudForms Management Engine Automate activities.
RedHat - Domain containing advanced operations, specifically interactions with supported cloud and infrastructure providers. This domain is locked with the following Namespaces:
- Cloud - Red Hat-supported cloud instance lifecycle from provisioning, retirement, methods, email.
- Infrastructure - Red Hat-supported cloud instance lifecycle from provisioning, retirement, methods, email.
- Integration - Used to interface with systems outside of CloudForms Management Engine. Use this namespace to integrate with additional systems.
You can copy classes and instances from locked Domains into your own custom domains.
Red Hat does not recommend changing any of the existing classes or instances shipped with the product as this may hinder the operation of the CloudForms Management Engine. You can link to these methods using relationships.
To reset the Automate model to default settings, navigate to Automate → Import/Export and click the Reset option.
2.2. Creating a Domain
-
Navigate to
Automate
→Explorer
. The default view is the Datastore. -
Click
(
Configuration
), then(
Add a New Domain
). -
Type in a unique
Name
andDescription
. Choose if the Domain isEnabled
. -
Click
Add
.
The new domain is created.
2.3. Editing a Domain
-
Navigate to
Automate
→Explorer
. The default view is the Datastore. - Select the Domain you want to edit.
-
Click
(
Configuration
), then(
Edit Selected Domain
). - Make the required edits.
-
Click
Save
.
You have edited the selected domain.
2.4. Deleting a Domain
-
Navigate to
Automate
→Explorer
. The default view is the Datastore. -
Select the
Domain
that you want to delete. -
Click
(
Configuration
), then(
Remove This Domain
). - A window to confirm the removal of Domain appears.
-
Click
OK
.
The selected Domain is deleted.
2.5. Changing Priority Order of Domains
Functions are executed depending on the order of Domain priority. Use this procedure to change the priority order of domains.
-
Navigate to
Automate
→Explorer
. The default view is the Datastore. - Select the Domains you want to change the priority order for.
-
Click
(
Configuration
), then(
Edit Priority Order of Domains
). - The list of Domains selected shows up. Note that you cannot change the priority of locked Domains and therefore locked Domains do not show up on the list.
- Select one or more consecutive groups to move up or down to change their priority as required.
-
Click
Save
.
2.6. Creating a Namespace
-
Navigate to
Automate
→Explorer
. The default view is the Datastore. - Navigate through the various Domains and Namespaces until you reach the desired location for your new Namespace.
-
Click
(
Configuration
), then(
Add a New Namespace
). -
Type in a unique
Name
andDescription
. -
Click
Add
.
The new Namespace is created.
2.7. Creating a Class
-
Navigate to
Automate
→Explorer
, navigate to the namespace you want to add a class to. -
Click
(
Configuration
), then(
Add a new Class
). -
Type in a unique
Name
andDescription
. -
If you want to use the schema from a class that has already been created, select it from the
Inherits From
dropdown. If the class that the new class inherits from changes, the new class will also change. -
Click
Add
.
The new class is created and you can create a schema, add instances and methods.
For each class, create a schema if you did not choose to inherit from an existing class. The schema can include attributes, methods, assertions, and relationships.
2.8. Creating a Schema for a Class
This procedure shows you how to create a schema.
-
Navigate to
Automate
→Explorer
, and click the class you want to define a schema for. -
Click on the
Schema
tab. -
Click
(
Configuration
), then(
Edit selected Schema
). -
Click
(
Click to add a new field
) to create a new field. -
Type in a
Name
for the new field. -
From
Type
, selectAssertion
,Attribute
,Method
,Relationship
, orState
. -
If applicable, select a
Data Type
and set aDefault Value
. -
Type in a user friendly
Display Name
andDescription
. -
Check
Sub
to enable the substitution syntax of${}
. Uncheck it if you want to use that syntax as a regular string. -
Fill in
Collect
andMessage
as required.Collect
is used to roll up values from resolved relationships. For example, a relationship can resolve to a large object tree. Usecollect
to specify how to pull out data from those child objects into the current object. If you givecollect
a name value, it will store the method result in an attribute of the current object with that name. -
On Entry
,On Exit
,On Error
,Max Retries
, andMax Time
are fields used mostly for state machines. Leave blank if not applicable. For more information, see the Provisioning Virtual Machines and Hosts guide, available from https://access.redhat.com/documentation/en/red-hat-cloudforms/. -
Click
(
Add this entry
) to confirm the fields values. - For each new field, repeat steps 4 through 10.
-
When you have created all of the fields, click
Save
.
The class schema is created, and you can now add instances to it.
You may need to edit a class schema to reorder, add, edit, or remove a field. Classes define the order in which fields are processed and you may need to process some items before others.
2.9. Editing a Field in a Schema
This procedure describes how to edit schema fields.
-
Navigate to
Automate
→Explorer
. - Click the class you want to define a schema for.
-
Click the
Schema
tab. -
Click
(
Configuration
), then(
Edit selected Schema
). - Make required changes to any of the definitions for the field.
-
To remove a field, click
(
Click to delete this field from the schema
). -
Click
Save
when you are finished editing the schema.
Once the schema is created, you can add instances and methods to the class.
2.10. Editing Schema Sequence
This procedure shows you how to change schema sequence.
-
Navigate to
Automate
→Explorer
. - Click the class you want to change the schema sequence for.
-
Click the
Schema
tab. -
Click
(
Configuration
), then(
Edit Sequence
). In the
Class Schema Sequencing
area, click the field you want to change the sequence for.-
To move a field up in the order of resolving an instance, click
(
Move selected field up
). -
To move a field down in the order of resolving an instance, click
(
Move selected field down
).
-
To move a field up in the order of resolving an instance, click
-
Click
Save
when you are finished editing the sequence.
2.11. Adding an Instance to a Class
This procedure shows you how to create an instance.
-
Navigate to
Automate
→Explorer
. - Click the class you want to define a schema for.
-
Click the
Instances
tab. -
Click
(
Configuration
), then(
Add a new Instance
). -
In the
Main Info
area, type in aName
,Display Name
andDescription
. -
In the
Fields
area, type in an appropriate value for each field, leave the field blank if no value is required, or use the default value. -
Click
Add
.
2.12. Copying a Class or Instance
-
Navigate to
Automate
→Explorer
. The default view is the Datastore. - Navigate through the various Domains and Namespaces until you reach the desired class or instance to copy.
-
Click
(
Configuration
), then either (Copy this Class
) or (Copy this Instance
) depending on the object chosen. -
Choose the target Domain in the
To Domain
drop-down menu. -
The object retains the same path as the
From Domain
and overrides the class inFrom Domain
if theTo Domain
has a high priority. You can also untick theCopy to same path
option to specify a new Namespace. -
Click
Add
.
2.13. Relationships
Relationships are used to connect to other instances in the Automation Datastore
. Relationships are formed using URI syntax. The following can also be passed through a relationship:
-
Use
#
to set the message to send to the item in the relationship. -
To pass an input to the method use
?
followed by the item to pass. -
If you want to use a substitution, the syntax is
$\{}
with the substitution located between the brackets.
Example | Explanation |
---|---|
/Cloud/VM/Provisioning/Naming/Default#create |
This relationships uses the Default instance of the Naming class, which provides a means for other classes to name virtual machines. The relationship sends the |
/Cloud/VM/Provisioning/StateMachines/VMProvision_VM/AcquireMACAddress#$\{#ae_message} |
This relationships substitutes the message to send to the AcquireMACAddress instance of the VMProvision_VM class with the value in |
/Cloud/VM/Retirement/Email/vm_retirement_emails?event=vm_retired |
Invokes the vm_retirement_emails instance of the Email class. Also sends the value |
/Service/Lifecycle/Retirement?service_id=$\{process#service_id} |
Invokes the Retirement instance of the Lifecycle class and send a replacement value in |
2.14. Methods
Methods are pieces of code associated with a class or object to perform a task. CloudForms Management Engine allows for Ruby methods. You can create your own methods or use relationships to link to pre-existing ones.
Red Hat CloudForms ships with a core set of Ruby gems used by the CloudForms Management Engine Rails Application. The Ruby gems in this set are subject to change, and have changed since CloudForms 3.1 (CloudForms Management Engine 5.3). If you are calling gems using Automate that are no longer in the CloudForms Management Engine Appliance, you can install them by using the gem install
command.
While gems can be imported into automation methods using require
, it is recommended that the authors of the automation methods clearly document the use of gems either in the core set or a custom set. It is the responsibility of the author of such custom automation to own the life cycle of any gem being referenced in those methods.
The Release Notes list Ruby gems that have been added, updated, or removed in the latest version of CloudForms Management Engine.
For lists of Ruby gems included in different CloudForms Management Engine releases, see the following article:
2.14.1. Creating a Method
This procedure shows you how to create a method.
-
Navigate to
Automate
→Explorer
, navigate to the class where you want to create a method. -
Click the
Methods
tab. -
Click
(
Configuration
),(
Add a New Method
). -
In the
Main Info
area, type in aName
andDisplay Name
. -
For
Location
, selectinline
. Once selected, you will be presented with aData
area in which to write or copy the script. -
Click
Validate
to check the syntax. -
Click
Add
.
2.14.2. Creating a Dynamic Content Dialog
The procedure describes the steps to create a dynamic content dialog.
-
Navigate to
Automate
→Explorer
. From the accordion menu, click
DOMAIN
→Cloud
→VM
→Operations
→Methods
.NoteDOMAIN must be a user-defined Domain and not the locked ManageIQ Domain. If necessary, you can copy the class from the ManageIQ domain into a custom domain.
This example uses the
Cloud
Namespace but can also use theInfrastructure
namespace.-
Click
(
Configuration
), then(
Add a new Instance
). -
In the
Main Info
area, enterName
=dynamic_list
, replacingdynamic_list
with an appropriate name for the method. -
Enter a
Display Name
andDescription
. -
In the
Fields
area, enterValue
=dynamic_list
. Leave the other fields blank or use the default values. -
Click
Add
. -
Navigate to
Methods
tab. -
In the
Main Info
area, enterName
= \\dynamic_list and populate theData
section with the example automate method below. -
Click
Add
. Set the automate entry point for the dialog control; use the new instance created in step four. You can create a new domain and copy the method to that domain.
# Automate Method dialog_field = $evm.object # sort_by: value / description / none dialog_field["sort_by"] = "value" # sort_order: ascending / descending #dialog_field["sort_order"] = "ascending" # data_type: string / integer dialog_field["data_type"] = "integer" # required: true / false # dialog_field["required"] = "true" dialog_field["values"] = {1 => "one", 2 => "two", 10 => "ten", 50 => "fifty"} dialog_field["default_value"] = 2
2.15. Simulation
2.15.1. Simulation
After your model is designed, use the simulate page to test it. It allows you to see the results in tree and XML view.
2.15.2. Simulating an Automate Model
This procedure shows you how to simulate an automate model.
-
Navigate to
Automate
→Simulation
. In
Object Details
, select a type of object from/System/Process/
that will initiate the model. TheMessage
should becreate
. Type in the name of theRequest
where you are starting from.Select the
Type
of item you want to run the simulation on. Then, select a specific one to use as the example.Check
Execute Methods
if you want to perform the model and not just simulate it.-
Type in the
Attribute/Value Pairs
fields if applicable. -
Click
Submit
.
Click on the Tree View
or XML View
tabs to see results.
2.16. Importing, Exporting, and Resetting the Datastore
2.16.1. Importing, Exporting, and Resetting the Datastore
The Automate Model can be exported and imported as a YAML file. CloudForms Management Engine allows you to back up your model by export. Red Hat may provide you with new or updated classes, and provides an import function for either a class or the entire model. Finally, you can reset the datastore to its default. Always be sure to export the current datastore before importing or resetting.
2.16.2. Exporting All Datastore Classes
This procedure shows you how export datastore classes as an XML file.
-
Navigate to
Automate
→Import/Export
. -
Click
(
Export all Datastore classes and instances to a file
). - Follow your browsers prompts to save the file.
The datastore is exported as a YAML file.
2.16.3. Importing Datastore Classes
This procedure shows you how to import datastore classes.
-
Navigate to
Automate
→Import/Export
. - Export the datastore so that you have a backup.
-
Click
Browse
to navigate to the location of the file to import. -
Click
Upload
.
The datastore is imported from the YAML file.
2.16.4. Resetting Datastore to Default
This procedure shows you how reset datastore to default.
-
Navigate to
Automate
→Import/Export
. - Export the datastore so that you have a backup.
-
Click
(
Reset all Datastore custom classes and instances to default
). - Read the prompt warning you that communication with the datastore will be lost and all classes and instances will be cleared and reset.
-
After reading the prompt, click
OK
.
Chapter 3. Invoking Automate
3.1. Automate Examples
This chapter describes the ways to invoke an Automate workflow. Automation can be initiated through an alert, an event, a CloudForms Management Engine application, or a custom button. The same automation process can be re-used across more than one of these. For example, using automation to remove orphaned virtual machines and instances could be initiated by:
- An administrator request from the CloudForms Management Engine console (from a custom button)
- An alert indicating the datastore has less than 20% free-space
- A virtual machine or instance unregistered event is detected
All invocations of an automate model must enter through the /System/Process
namespace.
3.2. Invoking Automate using a Custom Button
One of the ways to invoke an Automate model is to map an instance from the /System/Process/Request
class to a custom button. Before creating the button, you need to have an instance in the /System/Process/Request
class to map to it and a button group to assign it to.
Create buttons for a cluster, host, datastore, provider, virtual machines or cloud instances. When the button is clicked, the model will be invoked for the selected item. For each of these, you can have up to 15 buttons.
3.3. Creating a Custom Button Group
This procedure shows you how to create a custom button group.
-
Navigate to
Automate
→Customization
. -
Click the
Buttons
accordion. -
From the
Object Types
tree, select the type of object you want to create the button group for. -
Click
(
Configuration
),(
Add a new Button Group
). -
Type in a
Button Group
Text andButton Group Hover Text
, and select theButton Group Image
you want to use. - If custom buttons have already been created, assign them to the button group. If not, see Section 3.4, “Creating a Custom Button” to create custom buttons.
-
Click
Add
.
The button group will show in the object type you added the button to.
3.4. Creating a Custom Button
This procedure shows you how to create a custom button.
-
Navigate to
Automate
→Customization
. -
Click the
Buttons
accordion. -
From the
Object Types
tree, select the type of object you want to create the button for. -
Click
Unassigned Buttons
. Click
(
Configuration
), then(
Add a new Button
).NoteIf
(Add a new Button) is not available, that means you have not created a button group for that object. To continue, create a button group first. See Section 3.3, “Creating a Custom Button Group”
-
In
Action
, type in aButton Text
andButton Hover Text
, and select theButton Image
you want to use. -
Select a
Dialog
if applicable. -
In
Object Details
, selectRequest
from the/System/Process/
dropdown. By default, the message iscreate
. Do not change it. -
Type in a
Request
name for the/System/Process/Request
instance. -
Type in the
Attribute/Value Pairs
fields if applicable. -
Under
Visibility
, select whichAccount Roles
you want to have access to this button. -
Click
Add
when you have confirmed that the button accomplishes the task you want.
The button will show in the object type you added the button to.
3.5. Editing a Custom Button
This procedure shows you how to edit a custom button.
-
Navigate to
Automate
→Customization
. -
From the
Object Types
dropdown, select the type of object you want to edit the button for. - Click the button you want to edit.
-
Click
(
Configuration
),(
Edit this Button
). - Modify as required.
-
Click
Save
.
3.6. Deleting a Custom Button
This procedure shows you how to delete a custom button.
-
Navigate to
Automate
→Customization
, then select theButtons
accordion. -
From the
Object Type
tree in the accordion menu, select the type of object you want to remove the button from. -
Click
(
Configuration
). then click(
Remove this button
). -
Click
OK
to confirm that you want to delete this button.
3.7. Using a Custom Button
This procedure shows you how to use custom buttons to invoke a cluster, host, datastore, provider, virtual machine or instance.
- Go to the page for the item that you created a button for.
- Click the custom button group from the taskbar, and then your custom button.
The automate model is invoked for the specified item.
3.8. Initiating Automate from an Event
You can also use a CloudForms Management Engine Policy Event to initiate automation. You can either use the provided Raise Automation Event action or create a custom automation action. The first case will start in the /System/Process
class, but then go to the Event that initiated the Automate model in the /System/Process/Event Class
. If you create your own custom action, it will start from the /System/Process
class and then go to the /System/Process/Request Class
instead.
For example, suppose that you always want the same Automate model to occur when a virtual machine is created. You would use the Raise Automation Event Action. There are instances in the /System/Process/Event Class
for the following Events that you can select as part of a Policy:
3.9. Creating a Policy for Automate
This procedure shows you how to create a policy for automate.
-
Navigate to
Control
→Explorer
. -
Click the
Policies
accordion, and selectControl Policies
. -
Select
VM Control Policies
. -
Click
(
Configuration
), then(
Add a New Control Vm Policy
). -
Type in a
Description
. -
Uncheck
Active
if you do not want this policy processed even when assigned to a resource. -
Click
Add
. You are brought to the page where you add conditions and events to your new policy. Click
(
Configuration
), then(
Edit this Policy's Event assignments
).-
Check the events you want to use to send to an
Automate Model
. -
Click
Save
. -
From the
Events
area, click on theDescription of the Event
you want to assign an action to. -
Click
(
Edit Actions for this Policy Event
).
-
Check the events you want to use to send to an
-
Select
Raise Automation Event
, and click(
Move selected Actions into this Event
). -
Click
Save
.
You can now assign this policy to a Policy Profile
. Then, assign the policy profile to the virtual machines. Every time this event happens on the virtual machine the appropriate Automate Model will be initiated.
If you want the policy to initiate an Automate Model from the /System/Process/Request
class, then you can create your own custom action. Be sure to have an instance in the /System/Process/Request
class for it to map to.
3.10. Creating a Custom Automate Action
This procedure shows you how to create a custom Automate action.
-
Navigate to
Control
→Explorer
accordion. -
Click the
Actions
accordion. -
Click
(
Configuration
), then(
Add a new Action
). -
Type in a
Description
for the Action. -
Select
Invoke a Custom Automation
fromAction Type
. In
Custom Automation
,-
For
Message
, typecreate
. -
For
Request
, type in the name of the instance of the/System/Process/Request Class
in the second.
-
For
-
Type in the
Attribute/Value Pairs
fields if applicable. -
Click
Add
.
The action is created and can be added to a policy.
Appendix A. Objects
A.1. Virtual Machine Properties
When using these items in a method, prefix them with vm.
. For example: vm.storage_id.
Table A.1. Virtual Machine Properties
Friendly Name or Description | Raw Column Name |
---|---|
Allocated Disk Storage | allocated_disk_storage |
Autostart | autostart |
Blackbox Exists | blackbox_exists |
Blackbox Validated | blackbox_validated |
Boot Time | boot_time |
Busy | busy |
Cluster | ems_cluster_name |
Configuration XML | config_xml |
Connection State | connection_state |
CPU Affinity | cpu_affinity |
CPU Limit | cpu_limit |
CPU Reserve | cpu_reserve |
CPU Reserve Expand | cpu_reserve_expand |
CPU Shares | cpu_shares |
CPU Shares Level | cpu_shares_level |
Created on Time | ems_created_on |
Currently Used Space | used_storage_by_state |
Datastore Path | v_datastore_path |
Date Created | created_on |
Date Updated | updated_on |
Description | description |
Ems | ems_id |
Evm Owner | evm_owner_id |
Evm Owner Email | evm_owner_email |
Evm Owner Name | evm_owner_name |
CloudForms Management Engine Unique ID (Guid) | guid |
Format | format |
Host | host_id |
Host Name | host_name |
Id | id |
Is a Template | v_is_a_template |
Last Analysis Attempt On | last_scan_attempt_on |
Last Analysis Time | last_scan_on |
Last Compliance Status | last_compliance_status |
Last Compliance Timestamp | last_compliance_timestamp |
Last Perf Capture On | last_perf_capture_on |
Last Sync Time | last_sync_on |
Location | location |
Memory Limit | memory_limit |
Memory Reserve | memory_reserve |
Memory Reserve Expand | memory_reserve_expand |
Memory Shares | memory_shares |
Memory Shares Level | memory_shares_level |
Name | name |
OS Name | os_image_name |
Owner | owner |
Paravirtualization | paravirtualization |
Parent Cluster | v_owning_cluster |
Parent Datacenter | v_owning_datacenter |
Parent Folder (Hosts & Clusters) | v_owning_folder |
Parent Folder (VMs & Templates) | v_owning_blue_folder |
Parent Folder Path (Hosts & Clusters) | v_owning_folder_path |
Parent Folder Path (VMs & Templates) | v_owning_blue_folder_path |
Parent Host Platform | v_host_vmm_product |
Parent Resource Pool | v_owning_resource_pool |
Pct Free Disk | v_pct_free_disk_space |
Platform | platform |
Power State | power_state |
Previous State | previous_state |
Registered | registered |
Reserved | reserved |
Retired | retired |
Retirement | retirement |
Retires On | retires_on |
Service | service_id |
Smart | smart |
Standby Action | standby_action |
State Changed On | state_changed_on |
Storage | storage_id |
Storage Name | storage_name |
Template | template |
Thin Provisioned | thin_provisioned |
Tools Status | tools_status |
Total Provisioned Space | provisioned_storage |
Total Snapshots | v_total_snapshots |
Total Used Disk Space | used_disk_storage |
Uid Ems | uid_ems |
Uncommitted Space | uncommitted_storage |
Used Storage | used_storage |
V Pct Used Disk Space | v_pct_used_disk_space |
VDI Available | vdi_available |
VDI Connection DNS Name | vdi_connection_dns_name |
VDI Connection Logon Server | vdi_connection_logon_server |
VDI Connection Name | vdi_connection_name |
VDI Connection Remote IP Address | vdi_connection_remote_ip_address |
VDI Connection Session Name | vdi_connection_session_name |
VDI Connection Session Type | vdi_connection_session_type |
VDI Connection URL | vdi_connection_url |
VDI Endpoint IP Address | vdi_endpoint_ip_address |
VDI Endpoint MAC Address | vdi_endpoint_mac_address |
VDI Endpoint Name | vdi_endpoint_name |
VDI Endpoint Type | vdi_endpoint_type |
VDI User Appdata | vdi_user_appdata |
VDI User DNS Domain | vdi_user_dns_domain |
VDI User Domain | vdi_user_domain |
VDI User Home Drive | vdi_user_home_drive |
VDI User Home Path | vdi_user_home_path |
VDI User Home Share | vdi_user_home_share |
VDI User Logon Time | vdi_user_logon_time |
VDI User Name | vdi_user_name |
Vendor | vendor |
Version | version |
VMsafe Agent Address | vmsafe_agent_address |
VMsafe Agent Port | vmsafe_agent_port |
VMsafe Enable | vmsafe_enable |
VMsafe Fail Open | vmsafe_fail_open |
VMsafe Immutable VM | vmsafe_immutable_vm |
VMsafe Timeout (ms) | vmsafe_timeout_ms |
A.2. CloudForms Management Engine Methods for use in Ruby Scripts
To use one of these in one of your own Ruby methods, use the syntax of vm.method
. For example, to reboot the guest operating system, use vm.rebootGuest
.
Method | Description |
---|---|
start | Start Virtual Machine container. |
stop | Stop Virtual Machine container. |
suspend | Suspend Virtual Machine container. |
unregister | Unregister Virtual Machine. |
collect_running_processes | Collect the running processes from a started Virtual Machine. |
shutdownGuest | Shutdown the guest operating system of the VM container. Requires VMware tools (or vendors tools) installed on the guest. |
standbyGuest | Put the guest operating system into standby. Requires VMware tools (or vendors tools) installed on the guest. |
rebootGuest | Reboot the guest operating system. Requires VMware tools (or vendors tools) installed on the guest. |
A.3. Host Properties
When using these items in a method, prefix them with host, such as host.ems_id
.
Friendly Name or Description | Raw Column Name |
---|---|
All Enabled Ports | all_enabled_ports |
Annotation | v_annotation |
Authentication Status | Authentication_status |
Connection State | connection_state |
CPU usage MHz rate average over time period | cpu_usagemhz_rate_average_avg_over_time_period |
CPU usage MHz rate high over time period | cpu_usagemhz_rate_average_high_over_time_period |
CPU usage MHz rate low over time period | cpu_usagemhz_rate_average_low_over_time_period |
Custom Attribute 1 | custom_1 |
Custom Attribute 2 | custom_2 |
Custom Attribute 3 | custom_3 |
Custom Attribute 4 | custom_4 |
Custom Attribute 5 | custom_5 |
Custom Attribute 6 | custom_6 |
Custom Attribute 7 | custom_7 |
Custom Attribute 8 | custom_8 |
Custom Attribute 9 | custom_9 |
Date Created | created_on |
Derived memory usage average over time period | derived_memory_used_avg_over_time_period |
Derived memory usage high over time period | derived_memory_used_high_over_time_period |
Derived memory usage low over time period | derived_memory_used_low_over_time_period |
Ems | ems_id |
Enabled Inbound Ports | enabled_inbound_ports |
Enabled Outbound Ports | enabled_outbound_ports |
Enabled Run Level 0 Services | enabled_run_level_0_services |
Enabled Run Level 1 Services | enabled_run_level_1_services |
Enabled Run Level 2 Services | enabled_run_level_2_services |
Enabled Run Level 3 Services | enabled_run_level_3_services |
Enabled Run Level 4 Services | enabled_run_level_4_services |
Enabled Run Level 5 Services | enabled_run_level_5_services |
Enabled Run Level 6 Services | enabled_run_level_6_services |
Enabled TCP Inbound Ports | enabled_tcp_inbound_ports |
Enabled TCP Outbound Ports | enabled_tcp_outbound_ports |
Enabled UDP Inbound Ports | enabled_udp_inbound_ports |
Enabled UDP Outbound Ports | enabled_udp_outbound_ports |
EVM Unique ID (Guid) | guid |
Hostname | hostname |
Id | id |
IP Address | ipaddress |
Last Compliance Status | last_compliance_status |
Last Compliance Timestamp | last_compliance_timestamp |
Last Perf Capture On | last_perf_capture_on |
Last Analysis Time | last_scan_on |
Name | name |
OS Name | os_image_name |
Platform | platform |
Power State | power_state |
Region Description | region_description |
Region Number | region_number |
Reserved | reserved |
Service Names | service_names |
Settings | settings |
Smart | smart |
SSH Root Access | ssh_permit_root_login |
Uid Ems | uid_ems |
Date Updated | updated_on |
User Assigned Os | user_assigned_os |
Parent Cluster | v_owning_cluster |
Parent Datacenter | v_owning_datacenter |
Parent Folder (Hosts & Clusters) | v_owning_folder |
Total Datastores | v_total_storages |
Total VMs | v_total_vms |
VMM Build Number | vmm_buildnumber |
VMM Platform | vmm_product |
VMM Vendor | vmm_vendor |
VMM Version | vmm_version |
A.4. Provider Properties
When using these items in a method, prefix them with ems
, such as ems.ems_id
.
Friendly Name or Description | Raw Column Name |
---|---|
Aggregate VM CPUs | aggregate_vm_cpus |
Aggregate VM Memory | aggregate_vm_memory |
CPU Ratio | v_cpu_vr_ratio |
CPU Usage MHZ Rate Average High Over Time Period | cpu_usagemhz_rate_average_high_over_time_period" |
CPU Usage MHZ Rate Average Low Over Time Period | cpu_usagemhz_rate_average_low_over_time_period |
CPU Usage MHZ Rate Average Over Time Period | cpu_usagemhz_rate_average_avg_over_time_period |
Date Created | created_on |
Date Updated | updated_on |
Derived Memory Usage Rate Average High Over Time Period | derived_memory_used_high_over_time_period |
Derived Memory Usage Rate Average Low Time Period | derived_memory_used_low_over_time_period |
Derived Memory Usage Rate Average Over Time Period | derived_memory_used_avg_over_time_period |
Distributed Resource Scheduler Automation Level | drs_automation_level |
Distributed Resource Scheduler Enabled | drs_enabled |
Distributed Resource Scheduler Migration Threshold | drs_migration_threshold |
EMS ID | ems_id |
EVM Zone | zone_name |
High-Availability Admission Control | ha_admit_control |
High-Availability Enabled | ha_enabled |
High-Availability Max Failures | ha_max_failures |
Id | id |
Last Performance Data Captured | last_perf_capture_on |
Last Smart State Analysis | last_scan_on |
Memory Ratio | v_ram_vr_ratio |
Name | name |
Parent Datacenter | v_parent_datacenter |
Qualified Description | v_qualified_desc |
Region Description | region_description |
Region Number | region_number |
Reserved | reserved |
Total CPU Speed | aggregate_cpu_speed |
Total Hosts | total_hosts |
Total Memory | aggregate_memory |
Total Number of Logical CPUs | aggregate_logical_cpus |
Total Number of Physical CPUs | aggregate_physical_cpus |
Total Vms | total_vms |
Unique Identifier | uid_ems |
A.5. Storage Properties
When using these items in a method, prefix them with storage
, such as storage.name
.
Table A.2. Storage Properties
Friendly Name or Description | Raw Column Name |
---|---|
Date Created | created_on |
Date Updated | updated_on |
Disk Files Percent of Used | v_disk_percent_of_used |
Free Space | free_space |
Free Space Percent of Total | v_free_space_percent_of_total |
Id | id |
Last Analysis Time | last_scan_on |
Last Perf Capture On | last_perf_capture_on |
Location | location |
Multiple Host Access | multiplehostaccess |
Name | name |
Non-VM Files Percent of Used | v_debris_percent_of_used |
Other VM Files Percent of Used | v_vm_misc_percent_of_used |
Provisioned Space Percent of Total | v_provisioned_percent_of_total |
Reserved | reserved |
Size of Non-VM Files | v_total_debris_size |
Size of Other VM Files | v_total_vm_misc_size |
Size of VM Memory Files | v_total_vm_ram_size |
Size of VM Snapshot Files | v_total_snapshot_size |
Snapshot Files Percent of Used | v_snapshot_percent_of_used |
Store Type | store_type |
Total Hosts | v_total_hosts |
Total Managed Registered Vms | total_managed_registered_vms |
Total Managed Unregistered Vms | total_managed_unregistered_vms |
Total Provisioned Space | v_total_provisioned |
Total Space | total_space |
Total Unmanaged Vms | total_unmanaged_vms |
Total VMs | v_total_vms |
Uncommitted | uncommitted |
Used Space | v_used_space |
Used Space Percent of Total | v_used_space_percent_of_total |
VM Memory Files Percent of Used | v_memory_percent_of_used |
Appendix B. FAQs and Flows
B.1. Phase 1: Create Provision Request
Question | Answer |
---|---|
Where do I create a new provisioning profile based on a users LDAP group? | Navigate to [VM / Provisioning / Profile] of either the Cloud or Infrastructure namespace in your domain. |
Where can I specify a pre-dialog to present to a Requester in their LDAP group? | Custom pre-dialogs can be defined in [VM / Provisioning / Profile / <LDAP Group Name>] of either the Cloud or Infrastructure namespace in your domain. |
I would like to customize our dialogs. Where are all the dialogs kept? | All dialogs are located on each CloudForms Management Engine Appliance in the [/var/www/miq/vmdb/db/fixtures] directory. |
What happens if I do not specify any profiles for provisioning? | CloudForms Management Engine searches for a matching LDAP group in the [VM / Provisioning / Profile] class of either the Cloud or Infrastructure namespace in your domain. If an LDAP profile is NOT found then CloudForms Management Engine will use the .missing class instance. |
B.2. Phase 2: Request Approval
Question | Answer |
---|---|
Where can I specify auto-approval values on a per virtual machine template basis? | Tags can be assigned to templates in the form of [prov_max_vms, prov_max_cpus, prov_max_memory, prov_max_retirement_days]. |
Where can I modify the default Auto-Approval values? | These values can be set in the [Service / Provisioning / StateMachines / ServiceProvisionRequestApproval / Default] class instance in your domain. |
How can I customize the email that is sent when a request is approved? | The Request Approved email message can be modified in [VM / Provisioning / Email / MiqProvisionRequest_Approved] in either the Cloud or Infrastructure namespace of your domain. |
How can I customize the email that is sent when a request is denied? | The Request Denied email message can be modified in [VM / Provisioning / Email / MiqProvisionRequest_Denied] in either the Cloud or Infrastructure namespace of your domain. |
How can I customize the email that is sent when a request is not Auto-approved? | The Request Pending email message can be modified in [VM / Provisioning / Email / MiqProvisionRequest_Denied] in either the Cloud or Infrastructure namespace of your domain. |
If a Request Approval requires manual approval, how does an Approver approve the request? | Log into CloudForms Management Engine as an approver/admin and Navigate to Virtual Machines → Requests and then click on the request. |
B.3. Phase 3: Quota Validation
Question | Answer |
---|---|
Where in CloudForms Management Engine can I set default quota thresholds for users and groups? | These values can be set in the [VM / Provisioning / StateMachines / ProvisionRequestQuotaVerification] class instance of either the Cloud or Infrastructure namespace in your domain. |
Where in CloudForms Management Engine can I set individual and group quota thresholds? | Tags can be assigned to groups or users by navigating to Configuration → Access Control. The following are valid tags that can be assigned to group or individual users: [quota_max_cpu, quota_max_memory, quota_max_storage]. |
Where can I customize the way our virtual machines are named? | Virtual machine naming conventions can be altered using the methods in the [VM / Provisioning / Naming] class of either the Cloud or Infrastructure namespace in your domain. |
How can I customize the email that is sent when a request is denied? | The Request Denied email message can be modified in the [VM / Provisioning / Email / MiqProvisionRequest_Denied] in either the Cloud or Infrastructure namespace of your domain. |
B.4. Phase 4: Provisioning
Figure B.1. Target Type: Cloning a Template to a Virtual Machine

Figure B.2. Target Type: Clone to Template

Question | Answer |
---|---|
Where can I customize the email message that is sent upon provisioning completion? | This can be customized using the [VM / Provisioning / Email / MiqProvision_Complete] in either the Cloud or Infrastructure namespace of your domain. |
Where can I change what is put into the virtual machines Annotation after provisioning? | These settings can be modified by leveraging the *_PreProvision Ruby methods in [VM / Provisioning / StateMachines / Methods] in either the Cloud or Infrastructure namespace of your domain. |
Where do I set the default VC folder location for provisioning virtual machines? | This can be modified by leveraging by leveraging the *_PreProvision Ruby methods in [VM / Provisioning / StateMachines / Methods] in either the Cloud or Infrastructure namespace of your domain. |
Where can I modify the virtual machine customization spec mapping? | This can be modified by leveraging by leveraging the *_PreProvision Ruby methods in [VM / Provisioning / StateMachines / Methods] in either the Cloud or Infrastructure namespace of your domain. |
Where can I modify the Clone_to_Template state_machine? | Navigate to [VM / Provisioning / StateMachines / VMProvision_VM / template ] in either the Cloud or Infrastructure namespace of your domain. |
Where can I modify the Clone_to_VM state_machine? | Navigate to [VM / Provisioning / StateMachines / VMProvision_VM / clone_to_vm ] in either the Cloud or Infrastructure namespace of your domain. |
B.5. Phase 5: Retirement
Question | Answer |
---|---|
Where can I customize the email message that is sent upon completion of virtual machine retirement? | This can be customized using the [VM / Retirement / Email / vm_retirement_emails] in either the Cloud or Infrastructure namespace of your domain. |
Where can I customize the email message that is sent during virtual machine retirement warnings? | This can be customized using the [VM / Retirement / Email / vm_retirement_emails] in either the Cloud or Infrastructure namespace of your domain. |
If I want to customize what gets called during the retirement phase where should I look? | This can be customized using the [VM / Retirement / StateMachines / VMRetirement] in either the Cloud or Infrastructure namespace of your domain. |
How can I extend the virtual machine retirement date an additional number of days? | Create a custom button for virtual machines that launches [/System/Request/vm_retire_extend]. Then navigate to the [VM / Retirement / Email / vm_retire_extend] Ruby method in the Cloud and Infrastructure namespaces and set the vm_retire_extend_days value. |
Appendix C. Inline Method to Create a Provision Request
C.1. Ruby method
# CloudForms Management Engine Automate Method # $evm.log("info", "CloudForms Management Engine Automate Method Building VM Provisioning Request Started") # prov= $evm.root['miq_provision'] # arg1 = version args = ['1.1'] # arg2 = templateFields args << {'name' => 'App'} # arg3 = vmFields args << {'vm_name' => 'CRM_APP', 'request_type' => 'template'} # arg4 = requester args << {'owner_email' => 'admin@asd.com', 'owner_last_name' => 'Admin', 'owner_first_name' => 'Admin', 'user_name' => 'admin'} # arg5 = tags args << {'crm' => 'true'} # arg6 = WS Values args << nil # arg7 = emsCustomAttributes args << nil # arg8 = miqCustomAttributes args << nil $evm.log("info","Building provisioning request with the following arguments: <#{args.inspect}>") result = $evm.execute('create_provision_request', *args)