Red Hat CloudForms
4.0
Scripting Actions in CloudForms
Real-time, bi-directional process integration for CloudForms Management
Engine
Red Hat CloudForms Documentation
Team
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
Real-time, bi-directional process integration for CloudForms Management
Engine
Red Hat CloudForms Documentation Team
[email protected]
Legal Notice
Copyright © 2017 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is
available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must
provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity
logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other
countries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.
Java ® is a registered trademark of Oracle and/or its affiliates.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.
Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related to
or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other countries
and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or
sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Abstract
This guide provides instructions for scripting the method to implement adaptive automation for
management events and administrative or operational activities.
Table of Contents
Table of Contents
.CHAPTER
. . . . . . . . .1.. .CLOUDFORMS
. . . . . . . . . . . . . MANAGEMENT
. . . . . . . . . . . . . .ENGINE
. . . . . . . AUTOMATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . .
1.1. AUTOMATION
3
.CHAPTER
. . . . . . . . .2.. .AUTOMATE
. . . . . . . . . . MODEL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . .
2.1. AUTOMATE MODEL
4
2.2. CREATING A DOMAIN
5
2.3. EDITING A DOMAIN
5
2.4. DELETING A DOMAIN
5
2.5. CHANGING PRIORITY ORDER OF DOMAINS
6
2.6. CREATING A NAMESPACE
6
2.7. CREATING A CLASS
6
2.8. CREATING A SCHEMA FOR A CLASS
7
2.9. EDITING A FIELD IN A SCHEMA
8
2.10. EDITING SCHEMA SEQUENCE
8
2.11. ADDING AN INSTANCE TO A CLASS
9
2.12. COPYING A CLASS OR INSTANCE
2.13. RELATIONSHIPS
9
9
2.14. METHODS
2.15. SIMULATION
10
12
2.16. IMPORTING, EXPORTING, AND RESETTING THE DATASTORE
13
.CHAPTER
. . . . . . . . .3.. .INVOKING
. . . . . . . . . AUTOMATE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
...........
3.1. AUTOMATE EXAMPLES
15
3.2. INVOKING AUTOMATE USING A CUSTOM BUTTON
3.3. CREATING A CUSTOM BUTTON GROUP
15
15
3.4. CREATING A CUSTOM BUTTON
3.5. EDITING A CUSTOM BUTTON
15
16
3.6. DELETING A CUSTOM BUTTON
3.7. USING A CUSTOM BUTTON
3.8. INITIATING AUTOMATE FROM AN EVENT
17
17
17
3.9. CREATING A POLICY FOR AUTOMATE
3.10. CREATING A CUSTOM AUTOMATE ACTION
18
19
.APPENDIX
. . . . . . . . . A.
. . .OBJECTS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
...........
A.1. VIRTUAL MACHINE PROPERTIES
20
A.2. CLOUDFORMS MANAGEMENT ENGINE METHODS FOR USE IN RUBY SCRIPTS
27
A.3. HOST PROPERTIES
28
A.4. PROVIDER PROPERTIES
A.5. STORAGE PROPERTIES
32
35
.APPENDIX
. . . . . . . . . B.
. . .FAQS
. . . . .AND
. . . . FLOWS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
...........
B.1. PHASE 1: CREATE PROVISION REQUEST
38
B.2. PHASE 2: REQUEST APPROVAL
39
B.3. PHASE 3: QUOTA VALIDATION
B.4. PHASE 4: PROVISIONING
B.5. PHASE 5: RETIREMENT
40
41
43
.APPENDIX
. . . . . . . . . C.
. . .INLINE
. . . . . .METHOD
. . . . . . . . TO
. . . CREATE
. . . . . . . .A
. .PROVISION
. . . . . . . . . . .REQUEST
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
...........
C.1. RUBY METHOD
44
1
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
2
CHAPTER 1. CLOUDFORMS MANAGEMENT ENGINE AUTOMATION
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.
3
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
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.
4
CHAPTER 2. AUTOMATE MODEL
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.
Note
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
1. Navigate to Automate → Explorer. The default view is the Datastore.
2. Click
(Configuration), then
(Add a New Domain).
3. Type in a unique Name and Description. Choose if the Domain is Enabled.
4. Click Add.
The new domain is created.
2.3. EDITING A DOMAIN
1. Navigate to Automate → Explorer. The default view is the Datastore.
2. Select the Domain you want to edit.
3. Click
(Configuration), then
(Edit Selected Domain).
4. Make the required edits.
5. Click Save.
You have edited the selected domain.
2.4. DELETING A DOMAIN
1. Navigate to Automate → Explorer. The default view is the Datastore.
2. Select the Domain that you want to delete.
3. Click
(Configuration), then
(Remove This Domain).
4. A window to confirm the removal of Domain appears.
5
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
5. 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.
1. Navigate to Automate → Explorer. The default view is the Datastore.
2. Select the Domains you want to change the priority order for.
3. Click
(Configuration), then
(Edit Priority Order of Domains).
4. 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.
5. Select one or more consecutive groups to move up or down to change their priority as
required.
6. Click Save.
2.6. CREATING A NAMESPACE
1. Navigate to Automate → Explorer. The default view is the Datastore.
2. Navigate through the various Domains and Namespaces until you reach the desired location
for your new Namespace.
3. Click
(Configuration), then
(Add a New Namespace).
4. Type in a unique Name and Description.
5. Click Add.
The new Namespace is created.
2.7. CREATING A CLASS
1. Navigate to Automate → Explorer, navigate to the namespace you want to add a class
to.
2. Click
(Configuration), then
(Add a new Class).
3. Type in a unique Name and Description.
4. 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.
5. Click Add.
6
CHAPTER 2. AUTOMATE MODEL
The new class is created and you can create a schema, add instances and methods.
Note
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.
1. Navigate to Automate → Explorer, and click the class you want to define a schema for.
2. Click on the Schema tab.
3. Click
4. Click
(Configuration), then
(Edit selected Schema).
(Click to add a new field) to create a new field.
5. Type in a Name for the new field.
6. From Type, select Assertion, Attribute, Method, Relationship, or State.
7. If applicable, select a Data Type and set a Default Value.
8. Type in a user friendly Display Name and Description.
9. Check Sub to enable the substitution syntax of ${}. Uncheck it if you want to use that
syntax as a regular string.
10. Fill in Collect and Message as required. Collect is used to roll up values from resolved
relationships. For example, a relationship can resolve to a large object tree. Use collect
to specify how to pull out data from those child objects into the current object. If you give
collect a name value, it will store the method result in an attribute of the current object
with that name.
11. On Entry, On Exit, On Error, Max Retries, and Max 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/.
12. Click
(Add this entry) to confirm the fields values.
13. For each new field, repeat steps 4 through 10.
14. When you have created all of the fields, click Save.
The class schema is created, and you can now add instances to it.
7
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
Note
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.
1. Navigate to Automate → Explorer.
2. Click the class you want to define a schema for.
3. Click the Schema tab.
4. Click
(Configuration), then
(Edit selected Schema).
5. Make required changes to any of the definitions for the field.
6. To remove a field, click
(Click to delete this field from the schema).
7. 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.
1. Navigate to Automate → Explorer.
2. Click the class you want to change the schema sequence for.
3. Click the Schema tab.
4. Click
(Configuration), then
(Edit Sequence).
5. 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
field up).
To move a field down in the order of resolving an instance, click
selected field down).
6. Click Save when you are finished editing the sequence.
8
(Move selected
(Move
CHAPTER 2. AUTOMATE MODEL
2.11. ADDING AN INSTANCE TO A CLASS
This procedure shows you how to create an instance.
1. Navigate to Automate → Explorer.
2. Click the class you want to define a schema for.
3. Click the Instances tab.
4. Click
(Configuration), then
(Add a new Instance).
5. In the Main Info area, type in a Name, Display Name and Description.
6. 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.
7. Click Add.
2.12. COPYING A CLASS OR INSTANCE
1. Navigate to Automate → Explorer. The default view is the Datastore.
2. Navigate through the various Domains and Namespaces until you reach the desired class or
instance to copy.
3. Click
(Configuration), then either (Copy this Class) or (Copy this
Instance) depending on the object chosen.
4. Choose the target Domain in the To Domain drop-down menu.
5. The object retains the same path as the From Domain and overrides the class in From
Domain if the To Domain has a high priority. You can also untick the Copy to same
path option to specify a new Namespace.
6. 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.
9
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
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 create message to the class.
/Cloud/VM/Provisioning/StateMachines/VMProvisio
n_VM/AcquireMACAddress#$\{#ae_message}
This relationships substitutes the message to send
to the AcquireMACAddress instance of the
VMProvision_VM class with the value in
ae_message.
/Cloud/VM/Retirement/Email/vm_retirement_email
s?event=vm_retired
Invokes the vm_retirement_emails instance of the
Email class. Also sends the value vm_retired
in the event attribute, which is used in the
vm_retirement_emails method.
/Service/Lifecycle/Retirement?service_id=$\
{process#service_id}
Invokes the Retirement instance of the Lifecycle
class and send a replacement value in
process#service_id to the service_id
attribute.
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:
https://access.redhat.com/articles/1534753
2.14.1. Creating a Method
10
CHAPTER 2. AUTOMATE MODEL
2.14.1. Creating a Method
This procedure shows you how to create a method.
1. Navigate to Automate → Explorer, navigate to the class where you want to create a
method.
2. Click the Methods tab.
3. Click
(Configuration),
(Add a New Method).
4. In the Main Info area, type in a Name and Display Name.
5. For Location, select inline. Once selected, you will be presented with a Data area in
which to write or copy the script.
6. Click Validate to check the syntax.
7. Click Add.
2.14.2. Creating a Dynamic Content Dialog
The procedure describes the steps to create a dynamic content dialog.
1. Navigate to Automate → Explorer.
2. From the accordion menu, click DOMAIN → Cloud → VM → Operations → Methods.
Note
DOMAIN 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 the Infrastructure
namespace.
3. Click
(Configuration), then
(Add a new Instance).
4. In the Main Info area, enter Name = dynamic_list, replacing dynamic_list with an
appropriate name for the method.
5. Enter a Display Name and Description.
6. In the Fields area, enter Value = dynamic_list. Leave the other fields blank or use the
default values.
7. Click Add.
8. Navigate to Methods tab.
9. In the Main Info area, enter Name = \\dynamic_list and populate the Data section with the
example automate method below.
11
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
10. Click Add.
11. 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.
1. Navigate to Automate → Simulation.
2. In Object Details, select a type of object from /System/Process/ that will initiate the
model. The Message should be create. Type in the name of the Request where you are
starting from.
12
CHAPTER 2. AUTOMATE MODEL
3. Select the Type of item you want to run the simulation on. Then, select a specific one to use
as the example.
4. Check Execute Methods if you want to perform the model and not just simulate it.
5. Type in the Attribute/Value Pairs fields if applicable.
6. 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.
1. Navigate to Automate → Import/Export.
2. Click
(Export all Datastore classes and instances to a file).
3. Follow your browsers prompts to save the file.
13
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
The datastore is exported as a YAML file.
2.16.3. Importing Datastore Classes
This procedure shows you how to import datastore classes.
1. Navigate to Automate → Import/Export.
2. Export the datastore so that you have a backup.
3. Click Browse to navigate to the location of the file to import.
4. 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.
1. Navigate to Automate → Import/Export.
2. Export the datastore so that you have a backup.
3. Click
(Reset all Datastore custom classes and instances to
default).
4. Read the prompt warning you that communication with the datastore will be lost and all
classes and instances will be cleared and reset.
5. After reading the prompt, click OK.
14
CHAPTER 3. INVOKING AUTOMATE
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.
1. Navigate to Automate → Customization.
2. Click the Buttons accordion.
3. From the Object Types tree, select the type of object you want to create the button group
for.
4. Click
(Configuration),
(Add a new Button Group).
5. Type in a Button Group Text and Button Group Hover Text, and select the Button
Group Image you want to use.
6. 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.
7. Click Add.
The button group will show in the object type you added the button to.
3.4. CREATING A CUSTOM BUTTON
15
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
3.4. CREATING A CUSTOM BUTTON
This procedure shows you how to create a custom button.
1. Navigate to Automate → Customization.
2. Click the Buttons accordion.
3. From the Object Types tree, select the type of object you want to create the button for.
4. Click Unassigned Buttons.
5. Click
(Configuration), then
(Add a new Button).
Note
If
(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”
6. In Action, type in a Button Text and Button Hover Text, and select the Button
Image you want to use.
7. Select a Dialog if applicable.
8. In Object Details, select Request from the /System/Process/ dropdown. By
default, the message is create. Do not change it.
9. Type in a Request name for the /System/Process/Request instance.
10. Type in the Attribute/Value Pairs fields if applicable.
11. Under Visibility, select which Account Roles you want to have access to this button.
12. 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.
1. Navigate to Automate → Customization.
2. From the Object Types dropdown, select the type of object you want to edit the button
for.
3. Click the button you want to edit.
4. Click
(Configuration),
5. Modify as required.
16
(Edit this Button).
CHAPTER 3. INVOKING AUTOMATE
6. Click Save.
3.6. DELETING A CUSTOM BUTTON
This procedure shows you how to delete a custom button.
1. Navigate to Automate → Customization, then select the Buttons accordion.
2. From the Object Type tree in the accordion menu, select the type of object you want to
remove the button from.
3. Click
(Configuration). then click
(Remove this button).
4. 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.
1. Go to the page for the item that you created a button for.
2. 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:
17
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
3.9. CREATING A POLICY FOR AUTOMATE
This procedure shows you how to create a policy for automate.
1. Navigate to Control → Explorer.
2. Click the Policies accordion, and select Control Policies.
3. Select VM Control Policies.
4. Click
(Configuration), then
(Add a New Control Vm Policy).
5. Type in a Description.
6. Uncheck Active if you do not want this policy processed even when assigned to a
resource.
7. Click Add. You are brought to the page where you add conditions and events to your new
policy.
8. 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 the Description of the Event you want to assign
an action to.
18
CHAPTER 3. INVOKING AUTOMATE
Click
(Edit Actions for this Policy Event).
9. Select Raise Automation Event, and click
this Event).
(Move selected Actions into
10. 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.
Note
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.
1. Navigate to Control → Explorer accordion.
2. Click the Actions accordion.
3. Click
(Configuration), then
(Add a new Action).
4. Type in a Description for the Action.
5. Select Invoke a Custom Automation from Action Type.
6. In Custom Automation,
For Message, type create.
For Request, type in the name of the instance of the /System/Process/Request
Class in the second.
7. Type in the Attribute/Value Pairs fields if applicable.
8. Click Add.
The action is created and can be added to a policy.
19
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
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
20
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
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
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
21
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
22
Friendly Name or Description
Raw Column Name
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
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
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
23
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
24
Friendly Name or Description
Raw Column Name
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
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
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
25
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
26
Friendly Name or Description
Raw Column Name
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
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
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.
27
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
Method
Description
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.
28
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_peri
od
CPU usage MHz rate high over time period
cpu_usagemhz_rate_average_high_over_time_per
iod
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
CPU usage MHz rate low over time period
cpu_usagemhz_rate_average_low_over_time_peri
od
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
29
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
30
Friendly Name or Description
Raw Column Name
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
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
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
31
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
Friendly Name or Description
Raw Column Name
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.
32
APPENDIX A. OBJECTS
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_per
iod"
CPU Usage MHZ Rate Average Low Over Time
Period
cpu_usagemhz_rate_average_low_over_time_peri
od
CPU Usage MHZ Rate Average Over Time Period
cpu_usagemhz_rate_average_avg_over_time_peri
od
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
33
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
34
Friendly Name or Description
Raw Column Name
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
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
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
35
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
36
Friendly Name or Description
Raw Column Name
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
APPENDIX A. OBJECTS
Friendly Name or Description
Raw Column Name
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
37
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
APPENDIX B. FAQS AND FLOWS
B.1. PHASE 1: CREATE PROVISION REQUEST
38
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.
APPENDIX B. FAQS AND FLOWS
Question
Answer
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.
39
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
Question
Answer
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
40
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.
APPENDIX B. FAQS AND FLOWS
Question
Answer
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
41
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
42
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.
APPENDIX B. FAQS AND FLOWS
Question
Answer
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.
43
Red Hat CloudForms 4.0 Scripting Actions in CloudForms
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
VM Provisioning Request Started")
#
Building
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' => '[email protected]', '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)
44