Let’s jump right in and start writing our first automation script. In time-honored fashion we’ll write “Hello, World!” to the Automate Engine logfile.
Before we do anything, we need to ensure that the Automation Engine server role is selected on our CloudForms appliance. We do this from the Configure → Configuration menu, selecting the CloudForms server in the Settings accordion (see Figure 3-1).
The Automation Engine server role is now enabled by default in CloudForms 4.0, but it’s still worthwhile to check that this role is set on our CloudForms appliance.
Before we create our first automation script, we need to put some things in place. We’ll begin by adding a new domain called ACME. We’ll add all of our automation code into this new domain.
In the Automate Explorer, highlight the Datastore icon in the sidebar, and click Configuration → Add a New Domain (see Figure 3-2).
We’ll give the domain the name ACME
, give it the description ACME Corp.
, and ensure that the Enabled checkbox is selected.
Now we’ll add a namespace into this domain, called General. Highlight the ACME domain icon in the sidebar, and click Configuration → Add a New Namespace (see Figure 3-3).
Give the namespace the name General
and the description General Content
.
Now we’ll add a new class, called Methods.
Naming a class Methods
may seem somewhat confusing, but many of the generic classes in the ManageIQ and RedHat domains in the Automate Datastore are called Methods
to signify their general-purpose nature.
Highlight the General domain icon in the sidebar, and click Configuration → Add a New Class (see Figure 3-4).
Give the class the name Methods
and the description General Instances and Methods
. We’ll leave the display name empty for this example.
Now we’ll create a simple schema. Click the Schema tab for the Methods class, and click Configuration → Edit selected Schema (see Figure 3-5).
Click New Field, and add a single field with name execute
, type Method
, and data type String
(see Figure 3-6).
Click the checkmark in the lefthand column to save the field entry, and click the Save button to save the schema. We now have our generic class definition called Methods set up, with a simple schema that executes a single method.
Our first Automate method is very simple; we’ll write an entry to the automation.log file using this two-line script:
$evm
.
log
(
:info
,
"Hello, World!"
)
exit
MIQ_OK
First we need to create an instance from our class. In the Instances tab of the new Methods class, select Configuration → Add a New Instance (see Figure 3-7).
We’ll call the instance HelloWorld
, and it’ll run (execute) a method called hello_world (see Figure 3-8).
In the Methods tab of the new Methods class, select Configuration → Add a New Method (see Figure 3-9).
Name the method hello_world
, and paste our two lines of code into the Data window (see Figure 3-10).
We’ll run our new instance using the Simulation functionality of Automate, but before we do that, log in to CloudForms again from another browser or a private browsing tab, and navigate to Automate → Log in the WebUI.1
The CloudForms WebUI uses browser session cookies, so if we want two or more concurrent login sessions (particularly as different users), it helps to use different web browsers or private/incognito windows.
In the simulation, we actually run an instance called Call_Instance in the /System/Request/ namespace of the ManageIQ domain, and this in turn calls our HelloWorld instance using the namespace, class, and instance attribute/value pairs that we pass to it (see Chapter 11).
From the Automate → Simulation menu, complete the details (see Figure 3-11).
Click Submit.
If all went well, we should see our “Hello, World!” message appear in the automation.log file:
Invoking [inline] method [/ACME/General/Methods/hello_world] with inputs [{}] <AEMethod [/ACME/General/Methods/hello_world]> Starting <AEMethod hello_world> Hello, World! <AEMethod [/ACME/General/Methods/hello_world]> Ending Method exited with rc=MIQ_OK
Success!
In our example we used an exit status code of MIQ_OK
. Although with simple methods such as this we don’t strictly need to specify an exit code, it’s good practice to do so. When we build more advanced multimethod classes and state machines, an exit code can signal an error condition to the Automation Engine so that action can be taken.
There are four exit codes that we can use:
Method exited with rc=MIQ_OK
Method exited with rc=MIQ_WARN
Stopping instantiation because [Method exited with rc=MIQ_STOP]
Aborting instantiation because [Method exited with rc=MIQ_ABORT]
The difference between MIQ_STOP
and MIQ_ABORT
is subtle but comes into play as we develop more advanced Automate workflows.
MIQ_STOP
stops the currently running instance, but if this instance was called via a reference from another “parent” instance, the subsequent steps in the parent instance would still complete.
MIQ_ABORT
stops the currently running instance and any parent instance that called it, thereby terminating the Automate task altogether.
In this chapter we’ve seen how simple it is to create our own domain, namespace, class, instance, and method, and run our script from Simulation. These are the fundamental techniques that we use for all of our automation scripts, and we’ll use this knowledge extensively as we progress through the book.
We’ve also discovered the status codes that we should use to pass our exit status back to the Automation Engine.
1 Alternatively, ssh
into the CloudForms appliance as root and enter tail -f /var/www/miq/vmdb/log/automation.log
.
3.15.34.39