IBM Cloud Orchestrator

Version 2.4.0.2

User's Guide



IBM Cloud Orchestrator

Version 2.4.0.2

User's Guide



Note
Before using this information and the product it supports, read the information in Notices on page 1073.

This edition applies to IBM Cloud Orchestrator Version 2 Release 4 Fix Pack 2 (program number 5725-H28),
available as a licensed program product, and to all subsequent releases and modifications until otherwise indicated
in new editions.
The material in this document is an excerpt from the IBM Cloud Orchestrator knowledge center and is provided for
convenience. This document should be used in conjunction with the knowledge center.
Copyright IBM Corporation 2013, 2015.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Preface . . . . . . . . . . . . . . . xi
Who should read this information .

. xi

Chapter 1. Overview . . . . . . . . . 1
What is new . . . . . . .
Product architecture . . . . .
Product features and components
Pattern Engines . . . . . .
Overview of OpenStack. . . .
Multitenancy overview . . . .
Custom extensions . . . . .
Deployment modes . . . . .
IBM Platform Resource Scheduler

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

. . . .
. . . .
overview

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

1
2
4
6
8
8
. 11
. 12
. 12

Chapter 2. Installing . . . . . . . . . 15
Planning your installation . . . . . . . . .
Installation overview . . . . . . . . . .
Deployment topologies . . . . . . . . .
Hardware prerequisites . . . . . . . . .
Software prerequisites . . . . . . . . . .
Planning networks . . . . . . . . . . .
Using a virtual machine as a network server
Summary of features and capabilities of a
network server . . . . . . . . . .
Neutron scenarios . . . . . . . . . .
Planning PowerVC networks . . . . . .
Preparing for the installation . . . . . . . .
Setting up virtual machines . . . . . . . .
Preparing the IBM Cloud Orchestrator servers. .
Downloading the required image files . . . .
Installing the Deployment Service . . . . . . .
Understanding deployment templates . . . . .
Customizing deployment parameters . . . . . .
Deploying an IBM Cloud Orchestrator environment
Configuring an external database . . . . . .
Deploying the Central Servers . . . . . . .
Deploying a Region Server . . . . . . . .
Configuring a Region Server. . . . . . .
Installing a Hyper-V compute node . . .
Installing a KVM compute node . . . .
Configuring a PowerVC Region Server . .
Customizing a z/VM Region Server
deployment . . . . . . . . . . .
Installing Workload Deployer in non default
directories . . . . . . . . . . . . . .
Deploying the High-Availability Distributed
topology . . . . . . . . . . . . . . .
Installing System Automation Application
Manager . . . . . . . . . . . . . .
Installing the Central Servers . . . . . . .
Installing the Region Server . . . . . . . .
Installing a KVM Region Server with Neutron
network . . . . . . . . . . . . .
Installing a KVM Region Server with Nova
network . . . . . . . . . . . . .
Copyright IBM Corp. 2013, 2015

15
15
16
19
21
24
25
26
27
28
29
29
31
32
34
36
37
39
40
44
45
47
47
49
50
51
52
53
54
55
58
58
61

Installing a VMware Region Server with

Neutron network . . . . . . . . . . 63
Installing a VMware Region Server with Nova
network . . . . . . . . . . . . . 66
Verifying the installation . . . . . . . . . . 68
Installing IBM Cloud Orchestrator Enterprise
Edition . . . . . . . . . . . . . . . . 71
Quick start guide for metering and billing . . . 72
Post-installation tasks . . . . . . . . . . . 72
Assigning zones to domains and projects . . . 72
Configuring LDAP authentication . . . . . . 72
Configuring LDAP authentication
independently of the domain . . . . . . 73
Configuring LDAP authentication on a
domain-by-domain basis . . . . . . . . 76
Using external Directory Integration tools with
LDAP authentication . . . . . . . . . 77
LDAP Keystone configuration file reference . 78
Configuring Single Sign On to IBM Cloud
Orchestrator . . . . . . . . . . . . . 82
Setting NTP servers . . . . . . . . . . 83
Move the database to an external system . . . 84
Configuring Central Nodes to connect to
deployed virtual machines . . . . . . . . 85
OpenStack configuration . . . . . . . . . 87
Configuring OpenStack to support resource
overcommitment . . . . . . . . . . 87
Deploying multiple Cinder nodes as Storage
Nodes . . . . . . . . . . . . . . 87
Managing Nova networks . . . . . . . 88
Adding a network for a KVM Region . . 88
Adding a network for a VMware Region
90
Deleting the existing networks . . . . . 91
Associating a Nova network to a project. . 91
Managing Neutron networks . . . . . . 93
Adding Neutron networks . . . . . . 94
Associating a Neutron network to a project 97
Creating multiple networks assigned to
different projects. . . . . . . . . . 97
Managing flavors . . . . . . . . . . 100
Creating a flavor from the user interface
100
Creating a flavor from the command line 101
Customizing flavors for Power features
101
Deploying PowerVC virtual machines
using flavors . . . . . . . . . . 102
Advanced configuration on a VMware region
102
Connecting to multiple clusters . . . . . 104
Connecting to different datastores in the
same cluster . . . . . . . . . . . . 106
Connecting to resource pools . . . . . . 108
Connecting to multiple vCenters . . . . . 109
Enabling Storage DRS . . . . . . . . 112
Enabling datastore random selection. . . . 113
Configuring OpenStack to support thin
provisioning . . . . . . . . . . . . 113

iii

Configuring OpenStack to support linked

clones . . . . . . . . . . . . . .
Configuring vmware-discovery. . . . . .
Configuring vmware-discovery for multiple
vCenters . . . . . . . . . . . . .
Increasing shutdown timeout for virtual
machines . . . . . . . . . . . . .
Port group validation when using nova
network . . . . . . . . . . . . .
Opening VNC port on ESXi host to enable
the VNC console access . . . . . . . .
Supporting VMware vSphere 5.0 . . . . .
Supporting Cinder volumes in VMware
regions . . . . . . . . . . . . .
Managing content packs . . . . . . . . .
Installing and configuring content packs . .
Initializing the IaaS toolkit database . . . .
Configuring high availability . . . . . . .
Configuring the external database server for
the high-availability topology . . . . . .
Enabling autostart of System Automation
Application Manager . . . . . . . . .
Configuring System Automation Application
Manager . . . . . . . . . . . . .
Strengthening security . . . . . . . . .
Changing the Deployment Service passwords
Changing the various passwords . . . . .
Replacing the existing certificates. . . . .
Accessing Workload Deployer databases with
a different user . . . . . . . . . . .
Configuring options to delete running instances
Maintaining a deployed environment . . . . .
Starting and stopping the services in the
deployment service node . . . . . . . .
Scaling out a deployed environment. . . . .
Backing up and restoring Deployment Service
Upgrading . . . . . . . . . . . . . .
Upgrading from SmartCloud Orchestrator V2.3
or V2.3.0.1 . . . . . . . . . . . . .
Using the Deployment Service wizard to
upgrade . . . . . . . . . . . . .
Using the command-line interface to upgrade
Upgrading with an external database . . .
Configuring the upgrade configuration file
Requirements for upgrading a VMware
Region . . . . . . . . . . . . .
Migrating data in a VMware region . . . .
Post-upgrade configuration . . . . . . .
Upgrading from SmartCloud Cost
Management 2.1.0.3 . . . . . . . . .
Post configuration after Public Cloud
Gateway is upgraded. . . . . . . . .
Advanced post configuration after a VMware
region is upgraded . . . . . . . . .
Upgrading from IBM Cloud Orchestrator V2.4
on distributed deployment . . . . . . . .
Upgrading from IBM Cloud Orchestrator V2.4
for high availability . . . . . . . . . .
Configuring IBM Cloud Orchestrator after
upgrading from V2.4 . . . . . . . . . .
Disabling SSLv3 protocol in deployed instances

iv

IBM Cloud Orchestrator 2.4.0.2: User's Guide

113
114
116
117
117
117
118
118
118
118
118
119
119
121
122
125
125
127
136
142
142
143
143
144
146
147
147
150
152
158
158
164
164
167
167
168
168
171
174
176
180

Uninstalling . . . . . . . . . . . . .
Removing a KVM compute node . . . . .
Removing a region . . . . . . . . .
Troubleshooting installation . . . . . . .
Cannot create the external database . . . .
All-in-one deployment failed . . . . . .
Troubleshooting a high-availability installation
Upgrade fails with a DB2 error . . . . .
Troubleshooting upgrade . . . . . . .
Installation reference . . . . . . . . . .
Command-line methods . . . . . . . .
Using the command-line interface to deploy
IBM Cloud Orchestrator . . . . . . .
Deploying a Region Server (CLI method) .
Hypervisor-specific information when
deploying a Region Server (CLI method)
Customizable installation information . . .
Deployment templates for demo topology
Deployment templates for distributed
topology . . . . . . . . . . . .
Deployment templates for high-availability
distributed topology . . . . . . . .
Deployment parameters . . . . . . .
Quota-related installation parameters . .
System files modified by the installation
procedure . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

184
184
185
186
191
191
192
195
196
198
198

. 198
. 201
. 205
. 211
211
. 211
. 213
. 213
. 218
. 219

Chapter 3. Administering . . . . . . 221

Starting or stopping IBM Cloud Orchestrator . . .
Accessing IBM Cloud Orchestrator user interfaces
Managing the services . . . . . . . . . .
Managing services with SCOrchestrator.py . .
Running the SCOrchestrator.py script . . .
Running the SCOrchestrator.py script with
non-root user . . . . . . . . . . .
Managing IBM Cloud Orchestrator services
manually . . . . . . . . . . . . . .
Restarting NoSQL . . . . . . . . . . .
Managing high availability . . . . . . . . .
High-availability solutions . . . . . . . .
High-availability configurations . . . . .
Goal-driven automation . . . . . . . .
Using System Automation Application
Manager . . . . . . . . . . . . .
Using System Automation for Multiplatforms
System automation policies. . . . . . . .
Central Server 2 automation policy . . . .
Region Server automation policy . . . . .
Controlling the management stack . . . . .
Managing settings . . . . . . . . . . . .
Managing email delivery . . . . . . . .
Configuring OpenStack synchronization . . .
Customizing the user interface . . . . . .
Branding the user interface per domain . .
Metadata file properties in customization
file . . . . . . . . . . . . . .
Customizing the user interface . . . .
Dashboard extensions . . . . . . . .
Role based directory structure . . . . .
Navigation elements and extension
naming conventions . . . . . . . .

221
222
223
223
225
225
227
235
235
236
237
237
238
239
240
241
241
243
244
244
245
246
246
246
248
249
250
251

Packaging and deployment . . . . .

Managing security. . . . . . . . . . .
Model and terminology . . . . . . . .
User roles in IBM Cloud Orchestrator . . .
Regions, availability zones and quota . . .
Network isolation . . . . . . . . . .
Setting up PowerVC RSA keys . . . . .
Administering as cloud administrator . . .
Managing a domain . . . . . . . .
Creating a domain. . . . . . . .
Assigning a zone to a domain . . . .
Setting the default domain quotas . .
Editing the domain quotas . . . . .
Modifying the list of domain
administrators . . . . . . . . .
Setting a domain context . . . . .
Clearing the domain context . . . .
Managing projects . . . . . . . . .
Creating a project . . . . . . . .
Enabling a project . . . . . . . .
Editing a project . . . . . . . .
Disabling a project . . . . . . .
Deleting a project . . . . . . . .
Assigning a zone to a project . . . .
Configuring project quotas . . . . .
Reassigning VM instances to a project .
Customizing and extending the user
interface . . . . . . . . . . .
Modifying user assignments for a project
Managing groups . . . . . . . . .
Deleting a group . . . . . . . .
Managing users . . . . . . . . .
Creating a user . . . . . . . . .
Deleting a user . . . . . . . . .
Managing volumes . . . . . . . .
Managing networks . . . . . . . .
Creating a network . . . . . . .
Deleting a network . . . . . . .
Modifying a network . . . . . . .
Adding a subnet to an existing network
Administering as domain administrator . .
Managing domains . . . . . . . .
Managing projects . . . . . . . . .
Creating a project . . . . . . . .
Enabling a project . . . . . . . .
Edit a project . . . . . . . . .
Disabling a project . . . . . . .
Deleting a project . . . . . . . .
Creating a network for a project . . .
Deleting a network from a project . .
Modify the availability zones of a project
Modify the quota of a project . . . .
Modifying users in a project . . . .
Managing users . . . . . . . . .
Creating a user . . . . . . . . .
Deleting a User. . . . . . . . .
Auditing . . . . . . . . . . . . . .
Auditing login . . . . . . . . . . .
Audit events . . . . . . . . . . .
Audit event record attributes and usage tips .
Download options for audit event records . .

.
.
.
.
.
.
.
.
.
.
.
.
.

251
252
253
255
257
259
260
261
261
262
262
263
263

.
.
.
.
.
.
.
.
.
.
.
.

264
264
265
265
265
266
266
266
267
267
268
268

. 269
270
. 271
. 271
. 271
. 272
. 272
. 272
. 272
. 272
. 273
. 273
274
. 274
. 274
. 275
. 275
. 275
. 276
. 276
. 276
. 277
. 278
278
. 279
. 279
. 280
. 280
. 280
. 281
. 282
. 282
. 282
. 286

Retrieving audit data with the REST API

Deleting audit data to free storage . . .
Password management . . . . . . . .
Changing the password . . . . . . .
Resetting a password . . . . . . . .

.
.
.
.
.

.
.
.
.
.

286
290
292
292
292

Chapter 4. Managing orchestration

workflows . . . . . . . . . . . . . 293
Orchestration workflows . . . . . . . . .
Self-service offerings . . . . . . . . . .
Orchestration actions for Virtual System
Patterns (Classic) . . . . . . . . . . .
User actions . . . . . . . . . . . .
Event-triggered actions . . . . . . . .
Samples and standard extensions for orchestration
workflows . . . . . . . . . . . . . .
Working with Business Process Manager . . . .
Setting up IBM Process Designer . . . . . .
Adding users to IBM Process Designer . . .
Creating a process application in Process
Designer . . . . . . . . . . . . . .
Reusing processes and human services in a
process application . . . . . . . . .
Editing process applications and toolkits . .
Creating a process . . . . . . . . . . .
User input required at service request time
Making a new process available as a self-service
offering . . . . . . . . . . . . . .
Making a process available as an orchestration
action . . . . . . . . . . . . . . .
Upgrading a process on a development system
or production system . . . . . . . . . .
Configuring development mode . . . . .
Configuring production mode . . . . . .
Guidelines for working with Business Process
Manager . . . . . . . . . . . . . .

Chapter 5. Working with self-service

Using self-service . . . . . . . . . .
Viewing the dashboard . . . . . . .
Submitting a self-service request . . . .
Viewing the status of your requests . . .
Managing resources . . . . . . . .
Resource types . . . . . . . . .
Working with resources . . . . . .
Applying an action to a resource . .
Removing from the list of managed
servers in PowerVC . . . . . .
Managing virtual machines. . . . .
Deploying a virtual machine . . .
Managing virtual machine instances .
Working with Heat templates and stacks
Deploying a Heat template . . . .
Managing Heat stacks . . . . .
Managing key pairs . . . . . . .
Registering a key pair . . . . .
Unregistering a key pair. . . . .
Viewing the status of actions . . . . .
Working with patterns . . . . . . .
Managing the Inbox . . . . . . . .

293
294
294
295
295
296
296
297
297
298
299
300
300
301
302
302
304
305
305
306

309
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

309
309
311
311
311
311
312
312

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

313
313
314
315
317
317
321
322
322
322
323
323
323

Contents

Viewing the Inbox . . . . . .

Processing an Inbox assignment .
Designing self-service . . . . . .
Self-Service Catalog default contents.
Self-Service Catalog population tool .
Managing offerings . . . . . .
Creating an offering . . . . .
Modifying the access control list of
offering . . . . . . . . .
Managing categories . . . . . .
Creating a category . . . . .
Managing actions . . . . . . .
Creating an action . . . . . .
Modifying the access control list of

.
.
.
.
.
.
.
an
.
.
.
.
.
an

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

323
324
324
325
325
325
326

. . .
. . .
. . .
. . .
. . .
action

326
326
327
327
328
329

Chapter 6. Managing virtual images

331

Creating images for use in IBM Cloud Orchestrator

Creating base images . . . . . . . . . .
Creating Windows base images . . . . .
Adding cloudbase-init to Windows images
Installing virtio driver (KVM hypervisor
only) . . . . . . . . . . . . .
Running sysprep.exe . . . . . . . .
Adding cloud-init to Linux images . . . .
Adding cloud-init to images for Linux on
System z . . . . . . . . . . . . .
Creating images to deploy through virtual
system patterns or virtual application patterns .
Software prerequisites for Linux images
(KVM or VMware hypervisors) . . . . .
Software prerequisites for Microsoft
Windows images . . . . . . . . . .
Software prerequisites for images for Linux
on System z . . . . . . . . . . . .
Software prerequisites for AIX images . . .
Creating SmartCloud Orchestrator V2.3-like
images (advanced users only) . . . . . . .
Adding images to IBM Cloud Orchestrator . . .
Adding images to your OpenStack environment
Using OVA images from IBM Cloud Orchestrator
Catalog on KVM or VMware . . . . . . . .
Managing PowerVC images . . . . . . . .
Using OVA images from IBM Cloud
Orchestrator Catalog on PowerVC regions. . .
Making PowerVC images compatible with
Workload Deployer . . . . . . . . . .
Installing AIX enablement package . . . . .
Converting an OVA image to VMware format . .
Mapping the image created in IBM Cloud
Orchestrator . . . . . . . . . . . . . .
Using images created for SmartCloud Orchestrator
V2.3 . . . . . . . . . . . . . . . .

332
332
333
333
334
334
336
336
337
337
338
338
339
340
341
341
344
345
345
346
347
350
352
352

Chapter 7. Managing and deploying

virtual patterns. . . . . . . . . . . 353
Virtual pattern types . . . . .
Managing environment profiles .
Environment profiles overview
Managing environment profiles
interface . . . . . . . .

vi

. . . .
. . . .
. . . .
in the user
. . . .

IBM Cloud Orchestrator 2.4.0.2: User's Guide

.
.
.

. 353
. 354
. 354

. 355

Creating an environment profile . . . . .

Cloning an environment profile . . . . .
Editing an environment profile . . . . .
Environment Profiles window fields . . . .
Managing script packages . . . . . . . . .
Script packages overview . . . . . . . .
Using script packages with the user interface
Adding a script package. . . . . . . .
Cloning a script package . . . . . . .
Making script packages read-only . . . .
Associating a script package with a pattern
Deleting a script package . . . . . . .
Configuring script packages using the
cbscript.json object . . . . . . . . . .
Configuring JSON object script keys for
password protection . . . . . . . . .
Specifying alternate credentials for script
package execution . . . . . . . . . .
Configuring script packages by using the
extendedattributes.json object . . . . . .
Script package environment variables . . . .
Properties variable syntax . . . . . . . .
Script package examples. . . . . . . . .
Example script package to install an
application . . . . . . . . . . . .
Example script to configure the trace levels
Example script package to create a server
Example script package to create a
WebSphere Application Server cluster . . .
Managing add-ons . . . . . . . . . . .
Add-ons in the catalog . . . . . . . . .
Managing add-ons with the user interface . . .
Adding add-ons to the catalog. . . . . .
Cloning an add-on . . . . . . . . .
Editing an add-on . . . . . . . . . .
Making add-ons read-only . . . . . . .
Associating an add-on with a pattern . . .
Deleting an add-on . . . . . . . . .
Fields on the Add-Ons user interface . . .
Working with virtual system patterns . . . . .
Creating virtual system patterns . . . . . .
Importing virtual system patterns . . . . .
Cloning virtual system patterns . . . . . .
Exporting virtual system patterns . . . . .
Deleting virtual system patterns . . . . . .
Modifying virtual system patterns . . . . .
Making virtual system patterns read-only . . .
Deploying virtual system patterns . . . . .
Deploying Business Process Manager 8.5.5 and
DB2 10.5 virtual system patterns . . . . . .
Working with virtual system patterns (classic) . .
Supported virtual system patterns (classic) . .
Working with virtual system patterns (classic) in
the user interface . . . . . . . . . . .
Selecting a virtual system pattern (classic)
Using a predefined virtual system pattern
(classic) . . . . . . . . . . . .
Cloning an existing virtual system pattern
(classic) . . . . . . . . . . . .
Creating a virtual system pattern (classic)
Editing a virtual system pattern (classic) . .

355
359
360
362
365
365
366
367
370
371
371
373
374
381
382
383
388
390
391
404
405
406
407
408
409
410
411
412
413
414
414
415
416
419
419
426
427
427
428
428
429
430
434
434
435
436
437
437
438
440
442

Virtual system pattern (classic) editing

views and parts . . . . . . . . .
Ordering parts to run at deployment . .
Configuring parts . . . . . . . . . .
Configuring advanced options. . . . . .
Configuring advanced options for cluster
virtual system patterns (classic) . . . .
Configuring advanced options for
Intelligent Management Pack . . . . .
Configuring advanced messaging for
databases . . . . . . . . . . . .
Configuring advanced options for single
server virtual system patterns (classic) . .
Configuring database implemented
session persistence for Derby . . . . .
Making virtual system patterns (classic)
read-only . . . . . . . . . . . . .
Deploying a virtual system pattern (classic)
Deploying a pattern (classic) with
additional actions . . . . . . . . .
Deleting a virtual system pattern (classic)
Virtual system pattern (classic) windows . .
Fields on the Virtual System Patterns
(Classic) window . . . . . . . . .
Fields on the Pattern Editor window . .
Virtual system pattern (classic) processing . . .
Managing virtual system instances (classic) . .
Managing virtual system instances (classic)
with the user interface . . . . . . . .
Starting a persistent virtual system
instance (classic) . . . . . . . . .
Stopping a persistent virtual system
instance (classic) . . . . . . . . .
Removing a virtual system instance
(classic) . . . . . . . . . . . .
Creating a snapshot image . . . . . .
Restoring virtual system instances (classic)
from a snapshot image . . . . . . .
Deleting snapshot images . . . . . .
Virtual System Instances (classic) fields on
the user interface . . . . . . . . .
Accessing virtual machines in your virtual
system instance (classic) . . . . . . .
Expanding disk on deployed virtual
machines . . . . . . . . . . . .
Viewing the details for your virtual
machines . . . . . . . . . . . .
Managing pattern types . . . . . . . . . .
Viewing pattern types . . . . . . . . .
Viewing the plug-ins in the pattern types . . .
Importing pattern types . . . . . . . . .
Removing a pattern type . . . . . . . .
Upgrading pattern types . . . . . . . .
Upgrading a deployed pattern type . . . . .
Pattern type packaging reference . . . . . .
Working with virtual applications . . . . . .
Virtual application pattern components. . . .
Managing virtual applications . . . . . . .
Creating virtual application patterns. . . .
Editing virtual application patterns . . . .
Cloning virtual application patterns . . . .

443
446
447
449
451
455
460
461
463
463
464
468
468
469
470
472
475
476
476
478
479
480
481
482
483
484
485
486
487
492
493
494
494
495
496
497
497
498
501
503
503
505
505

Deleting virtual application patterns. . . .

Creating virtual application layers . . . .
Editing virtual application layers . . . . .
Deleting virtual application pattern layers
Importing virtual application pattern layers
Working with virtual application templates
Creating a virtual application template
Creating virtual applications from
templates . . . . . . . . . . . .
Cloning a virtual application template . .
Editing virtual application templates . .
Importing a virtual application template
Exporting a virtual application template
Removing a virtual application template
Working with virtual application pattern
plug-ins . . . . . . . . . . . . . .
Managing system plug-ins . . . . . . .
Plug-ins shipped with pattern types . . .
Adding system plug-ins to the catalog . .
Deleting plug-ins from the catalog . . .
Virtual application pattern components. . .
Application components. . . . . . .
Database components . . . . . . .
User Registry components . . . . . .
Messaging components . . . . . . .
OSGi components . . . . . . . . .
Transaction processing components . . .
Other components . . . . . . . . .
Policies . . . . . . . . . . . .
Developing plug-ins . . . . . . . . .
Plug-in Development Kit . . . . . .
Plug-in development guide . . . . . .
Samples . . . . . . . . . . . .
Deploying virtual applications. . . . . . .
Deploying virtual application patterns . . .
Deploying virtual application templates . .
Securing virtual applications . . . . . .
Securing virtual application instances with
SSL. . . . . . . . . . . . . .
Configuring SSH key-based access during
application deployment . . . . . . .
Configuring SSH key-based access in the
user interface . . . . . . . . . .
LTPA keys . . . . . . . . . . .
Working with virtual application instances . .
Monitoring virtual application instances . .
Viewing virtual application instance logs
Working with shared services . . . . . . . .
Deploying shared services . . . . . . . .
Monitoring shared services . . . . . . . .
Deploying a monitoring shared service . . .
Enabling TOSCA support for IBM Cloud
Orchestrator . . . . . . . . . . . . . .
Configuring the RPM repository for the
deployment of TOSCA patterns . . . . . .
Configuring an RPM repository of type ISO
Image on NFS . . . . . . . . . . .
Configuring an RPM repository of type FTP
Configuring an RPM repository of type
HTTP . . . . . . . . . . . . . .

Contents

506
506
507
508
509
509
510
511
512
513
513
514
514
515
515
516
516
516
517
518
532
542
553
558
563
568
569
575
580
584
628
636
636
640
642
643
645
646
647
648
650
650
652
652
653
654
655
656
656
657
657

vii

Disabling the configuration of an RPM

repository . . . . . . . . . . .
Configuring Chef support for TOSCA based
virtual application patterns . . . . . . .

Chapter 8. Managing a hybrid cloud

. 658
. 658

661

Public Cloud Gateway overview . . . . . . .

Capabilities and limitations. . . . . . . .
Amazon VPC support . . . . . . . .
Amazon API support . . . . . . . . .
OpenStack API support . . . . . . . .
Configuring the Public Cloud Gateway. . . .
SSH key management . . . . . . . . .
Multitenancy support . . . . . . . . .
Quota support overview. . . . . . . . .
Network planning . . . . . . . . . . .
Upgrading . . . . . . . . . . . . . .
Upgrading and cache configuration . . . . .
Upgrading Amazon EC2 multi-tenancy . . . .
Performing post-upgrade configuration tasks
Upgrading SoftLayer datacenter names from 2.4
to 2.4.0.x . . . . . . . . . . . . . .
Common configuration tasks . . . . . . . .
Prerequisites. . . . . . . . . . . . .
Creating a supported image . . . . . . .
Creating cloud-init images for Nova
deployment for Linux . . . . . . . .
Creating Workload Deployer cloud images
for Linux . . . . . . . . . . . . .
Enable Amazon EC2 image for scp-init
activation. . . . . . . . . . . .
Password authentication on Amazon EC2
images . . . . . . . . . . . .
Creating cloud-init images for Nova
deployment on Windows . . . . . . .
Creating Workload Deployer cloud images
for Windows on Softlayer . . . . . . .
Creating Workload Deployer cloud images
for Windows on EC2 . . . . . . . . .
Tagging images with the configuration
strategy . . . . . . . . . . . . .
Configuring flavors . . . . . . . . . .
Configuring quotas . . . . . . . . . .
Configuring caching . . . . . . . . . .
Changing the Keystone administrator password
Changing a region name . . . . . . . .
Restarting the Public Cloud Gateway . . . .
Remote Cloud API proxy configuration. . . .
Managing Amazon EC2 using the Public Cloud
Gateway . . . . . . . . . . . . . . .
Configuring the Public Cloud Gateway for
Amazon EC2 . . . . . . . . . . . .
Configure regions in the config.json file . .
Configure cloud credentials in the
/opt/ibm/pcg/etc/credentials.json file .
Configuring subnets and security groups in a
non-default VPC region . . . . . . . . .
Managing SoftLayer using the Public Cloud
Gateway . . . . . . . . . . . . . . .
Integrating SoftLayer using the Public Cloud
Gateway . . . . . . . . . . . . . .

viii

IBM Cloud Orchestrator 2.4.0.2: User's Guide

661
662
664
664
664
666
667
667
669
670
673
673
673
674

Configuring the Public Cloud Gateway for

SoftLayer . . . . . . . . . . . . . .
Managing non-IBM supplied OpenStack using the
Public Cloud Gateway . . . . . . . . . .
Configure the Public Cloud Gateway regions for
non-IBM supplied OpenStack . . . . . . .
Configure non-IBM supplied OpenStack EC2
credentials . . . . . . . . . . . . .
Performing post-configuration tasks . . . . . .
Reference. . . . . . . . . . . . . . .
Key pairs . . . . . . . . . . . . . .
Command-line interface scripts . . . . . .
Password authentication on Amazon EC2
images . . . . . . . . . . . . . .

703
708
709
711
714
715
715
715
716

Chapter 9. Integrating . . . . . . . . 717

679

Integrating with IBM Tivoli Monitoring . . .

Preparing a base operating system . . . .
Database setup . . . . . . . . . . .
Installing IBM Tivoli Monitoring . . . . .
Packages used for installation . . . . .
Creating a warehouse database . . . . .
Monitoring Agent for Linux . . . . . .
Monitoring Agent for Kernel-based virtual
machines . . . . . . . . . . . . .
OpenStack hypervisors . . . . . . . .
Integrating with IBM Endpoint Manager . . .
Installing Endpoint Manager agent to existing
computers . . . . . . . . . . . .
Installing Endpoint Manager agents during
virtual machine deployment . . . . . .

679

Chapter 10. Reporting. . . . . . . . 733

675
675
675
676
676
677

680
684
685
687
688
690
691
693
693
695
695
697
697
698
700
702
702
703

Tivoli Common Reporting .

.
.
.
.
.
.
.

717
717
718
718
719
720
721

. 721
. 722
. 722
. 723
. 723

. 733

Chapter 11. Reference. . . . . . . . 735

Using the command-line interface . . . . . .
Command-line interface overview . . . . .
Downloading and configuring the
command-line interface . . . . . . . . .
Invoking the command-line interface . . . .
Getting help on the command-line interface . .
Command-line interface resource object
reference . . . . . . . . . . . . . .
AddOn command-line interface reference . .
Audit logging command-line interface
reference . . . . . . . . . . . . .
Cloud group command-line interface
reference . . . . . . . . . . . . .
Environment profiles command-line interface
reference . . . . . . . . . . . . .
Environment profiles on the
command-line interface . . . . . . .
Environment profile clouds on the
command-line interface . . . . . . .
Environment profile cloud IP groups on
the command-line interface . . . . . .
Hypervisor command-line interface reference
Image command-line interface reference . .

735
735
736
737
739
740
740
744
745
748
749
752
755
758
762

Installation Manager repository

command-line interface reference . . . . .
IP command-line interface reference . . . .
IP group command-line interface reference
Mail delivery command-line interface
reference . . . . . . . . . . . . .
Network command-line interface reference
Pattern type command-line interface . . .
Plug-in command-line interface reference . .
Problem determination command-line
interface reference . . . . . . . . . .
Script package command-line interface
reference . . . . . . . . . . . . .
Snapshots on the command-line interface . .
Storage command-line interface reference . .
Virtual application instance command-line
interface reference . . . . . . . . . .
Virtual application pattern command-line
interface reference . . . . . . . . . .
Virtual images command-line interface
reference . . . . . . . . . . . . .
Virtual image mappings command-line
interface reference . . . . . . . . . .
Virtual machines command-line interface
reference . . . . . . . . . . . . .
Virtual system instances command-line
interface reference . . . . . . . . . .
Virtual system instances (classic)
command-line interface reference . . . . .
Virtual system patterns command-line
interface reference . . . . . . . . . .
Virtual system patterns (classic)
command-line interface reference . . . . .
Importing and exporting virtual system
patterns (classic) . . . . . . . . .
Virtual system patterns (classic) on the
command-line interface . . . . . . .
Virtual system pattern (classic) parts on
the command-line interface . . . . . .
Virtual system pattern (classic) scripts on
the command-line interface . . . . . .
Parts on the command-line interface. . .
Resources, resource collections, and methods
Resources on the command line . . . . .
Resource collections on the command line
Resource methods on the command-line
interface . . . . . . . . . . . . .
Resource collections methods on the
command-line interface . . . . . . . .
Wizard objects on the command-line interface
ACL object . . . . . . . . . . . .
Additional command-line interface utilities . .
REST API reference . . . . . . . . . . .
REST API frameworks . . . . . . . . .
Orchestration actions REST API . . . . . .
List all orchestration action entries . . . .
Retrieve an orchestration action entry . . .
Add or update an entry in the orchestration
actions . . . . . . . . . . . . .
Delete an orchestration action entry . . . .
Get entries for a specific virtual system. . .

763
764
767
770
770
772
774
775
777
781
783
784
786
792
797
799
803
804
812
818
818
821
827
833
839
842
843
847
848
854
860
862
865
867
868
869
869
870
870
871
872

Business Process Manager Invoker REST API

Retrieve available BPM Business Processes
List all BPM Business Processes . . . .
Get entries for a specific BPM Business
Process . . . . . . . . . . . .
Retrieve available human services . . . .
List all human services . . . . . . .
Get entries for a specific human service
Retrieve the Inbox . . . . . . . . . .
List all Inbox items . . . . . . . .
Get entries for a specific Inbox item . . .
Service instance REST API . . . . . . . .
Get entries for a specific service instance . .
Metadata parameters REST API . . . . .
Get parameters of specific metadata . . .
Post metadata parameters . . . . . .
Delete parameters of specific metadata
Virtual machines parameters REST API. . .
Get parameters of a specific virtual
machine . . . . . . . . . . . .
Post virtual machine parameters . . . .
Delete parameters of specific virtual
machines . . . . . . . . . . . .
Deployment parameters REST API . . . . .
Get deployment parameters for a specific
instance . . . . . . . . . . . . .
Post deployment parameters for a specific
instance . . . . . . . . . . . . .
Core Services REST API . . . . . . . . .
Core Services REST API overview . . . .
Offering REST API V2 . . . . . . . .
Categories . . . . . . . . . . .
Offering attributes . . . . . . . . .
Offering instances . . . . . . . . .
Launching an offering via Offering REST
API. . . . . . . . . . . . . .
Resource instances REST API . . . . . .
Resource instance providers . . . . .
Task engine REST API V2 . . . . . . .
Configuration providers REST API . . . .
Managing entities using Core REST APIs
Managing entities using actions . . . .
Core REST API for compatibility with earlier
versions . . . . . . . . . . . . .
Self-service offering REST API . . . . .
Self-service catalog REST API . . . . .
Task engine REST API . . . . . . .
Workload Deployer REST API . . . . . . .
Environment profiles REST API . . . . .
Log viewer manager REST API . . . . .
Logging REST API . . . . . . . . .
Monitoring REST API . . . . . . . .
Pattern types REST API . . . . . . . .
Plug-ins REST API . . . . . . . . .
Shared services REST API . . . . . . .
Version REST API . . . . . . . . . .
Virtual appliance instances REST API . . .
Virtual application instances REST APIs . .
Virtual application patterns REST API . . .
Virtual images REST API . . . . . . .
Virtual machines REST API. . . . . . .
Contents

873
873
873
874
874
874
875
876
876
877
879
879
883
883
884
884
885
885
885
886
886
886
887
888
888
891
891
894
895
900
904
911
918
921
921
921
927
927
941
946
950
950
953
955
957
961
964
966
968
968
973
976
985
990

ix

Virtual
Virtual
Virtual
Virtual

system
system
system
system

instances REST API . . . . 996

instances (classic) REST API 1000
patterns REST API . . . . 1010
patterns (classic) REST API
1019

Chapter 12. Troubleshooting . . . . 1025

Finding the log files . . . . . . . . . . .
Problem determination with pdcollect tool . . .
Running the pdcollect tool . . . . . . .
Running the pdcollect tool with non-root user
Setting logging levels . . . . . . . . . .
Workload Deployer log files . . . . . . . .
Known errors and limitations . . . . . . .
Product limitations . . . . . . . . . .
Unable to reduce the disk size of VMware
and KVM virtual machines . . . . . .
Disk resize of a template with multiple
disks . . . . . . . . . . . . . .
Hypervisor errors . . . . . . . . . .
Image errors . . . . . . . . . . . .
Instance errors . . . . . . . . . . .
Deployment errors . . . . . . . . . .
Setting the host name when deploying a
Windows system . . . . . . . . . .
Unable to deploy a virtual system pattern
with a non-admin user . . . . . . . .
Error displayed when deploying a virtual
system pattern . . . . . . . . . .
Unable to deploy WebSphere Application
Server OVA image . . . . . . . . .
Deployment of the virtual system pattern
fails due to the name of the virtual machine.
Script execution does not report failing
condition . . . . . . . . . . . .
No valid host was found . . . . . . .
nova command errors and limitations . . . .
Security limitations . . . . . . . . . .
Unable to change the flavor of VMware virtual
machines . . . . . . . . . . . . .
Error message displayed when trying to start a
virtual system . . . . . . . . . . . .
Unable to list keystone endpoints on the
Region Server . . . . . . . . . . . .
Unable to log in by using an LDAP user . . .
Unable to add disk to SLES instance . . . .
Errors of 32-bit library files libstdc++.so.6
and /lib/libpam.so* were not found in
db2prereqcheck.log . . . . . . . . . .
Unable to reach one of the addresses if
multiple NICs of a Linux virtual machine are
deployed . . . . . . . . . . . . .
Unable to access the Administration user
interface. . . . . . . . . . . . . .
User name and password for vCenter are
incorrect. . . . . . . . . . . . . .
Hypervisors remain in maintenance mode . .
Unable to list all the existing resources . . .
Cannot configure a nova compute service to
connect to more than four vCenter clusters . .

IBM Cloud Orchestrator 2.4.0.2: User's Guide

1025
1026
1027
1028
1029
1031
1032
1032
1034
1035
1035
1037
1038
1039
1039
1040
1041
1041
1042
1042
1043
1043
1044

Failed to start a virtual system instance on a

KVM Region . . . . . . . . . . . .
Failed to use the SSH key file to deploy IBM
Cloud Orchestrator . . . . . . . . . .
Lost metadata after updating the aggregate
availability zone . . . . . . . . . . .
Cannot log in to Administration user interface
if Public Cloud Gateway-only region installed .
Unable to deploy VMware virtual system
pattern in multi-language environment . . .
Users cannot log in to the user interface . . .
Re-configuring an existing Nova network . .
Troubleshooting a VMware region . . . . . .
Troubleshooting PowerVC region . . . . . .
Troubleshooting Workload Deployer . . . . .
Troubleshooting Business Process Manager . . .
Troubleshooting the Public Cloud Gateway . . .
Loss of functionality in Public Cloud Gateway
cloud groups . . . . . . . . . . . .
Region names displayed incorrectly in the
Virtual Image page . . . . . . . . . .
Unable to connect to a public cloud due to
missing credentials . . . . . . . . . .
Unable to deploy instance to non-IBM supplied
OpenStack . . . . . . . . . . . . .
Inconsistencies in deployed instance names
MAC address field is empty . . . . . . .
Quota troubleshooting . . . . . . . . .
Failure to generate admin token . . . . . .
Time-outs during resource modification
processing . . . . . . . . . . . . .
Problem configuring privateNetworkOnly on
Amazon EC2 Subnets . . . . . . . . .
Debugging image templates . . . . . . .
Deploying an instance with an additional
disk to SoftLayer fails due to timeout . . .

1051
1051
1052
1052
1052
1054
1055
1055
1056
1059
1061
1062
1062
1063
1063
1064
1064
1065
1065
1066
1067
1067
1068
1069

1044

Accessibility features for IBM Cloud

Orchestrator . . . . . . . . . . . 1071

1044

Notices . . . . . . . . . . . . . 1073

1045
1046
1046

Programming interface information . . . . . 1075

Trademarks . . . . . . . . . . . . . 1075
Terms and conditions for product documentation 1075
IBM Online Privacy Statement . . . . . . . 1076

1047

1047
1048
1048
1050
1050
1050

Glossary . . . . . . . . . . . . . 1077
A
B
C
E
H
K
P
R
S
T
V

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

1077
1078
1078
1078
1078
1078
1079
1079
1079
1079
1079

Preface
This publication documents how to use IBM Cloud Orchestrator.

Who should read this information

This information is intended for cloud administrators who install and configure
IBM Cloud Orchestrator, and for users who work with this product.

Copyright IBM Corp. 2013, 2015

xi

xii

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 1. Overview
With IBM Cloud Orchestrator, you can manage your cloud infrastructure.
IBM Cloud Orchestrator helps you with end-to-end service deployment across
infrastructure and platform layers. It also provides integrated IT workflow
capabilities for process automation and IT governance, resource monitoring, and
cost management. The product offers you an extensible approach to integration
with existing environments such as network management tools. It facilitates
integration with customer-specific service management processes, such as those
defined in the IT infrastructure library (ITIL).
Using IBM Cloud Orchestrator, you have a consistent, flexible, and automated way
of integrating the cloud with customer data center policies, processes, and
infrastructures across various IT domains, such as backup, monitoring, and
security. Use the intuitive, graphical tool in IBM Cloud Orchestrator to define and
implement business rules and IT policies. You can connect the aspects of different
domains into a consistent orchestration of automated and manual tasks to achieve
your business goals.
IBM Cloud Orchestrator is based on a common cloud platform that is shared
across IBM's Cloud offerings. This common cloud stack provides a common
realization of the core technologies for comprehensive and efficient management of
cloud systems.
You choose between two editions: IBM Cloud Orchestrator and IBM Cloud
Orchestrator Enterprise Edition which also includes Monitoring and Cost
Management.

What is new
The following enhancements were introduced in the current release.

What is new in version 2.4.0.1

Hyper-V support
IBM Cloud Orchestrator now supports Hyper-V hypervisors in addition to
KVM, VMware, PowerVC, and z/VM hypervisors.

What is new in version 2.4

Simplified architecture
Image Construction and Composition Tool, Virtual Image Library, IaaS
gateway, and SmartCloud Entry are no longer included in IBM Cloud
Orchestrator. This architecture change simplifies the creation, update, and
management of images to be deployed through IBM Cloud Orchestrator.
Monitoring dashboard
It provides basic monitoring information related to your infrastructure.
Simplified single virtual machine deployment
Deploy single instances without creating a virtual system pattern.

Copyright IBM Corp. 2013, 2015

Support for OpenStack Heat templates and stack

Import OpenStack Heat templates and deploy and manage OpenStack
Heat stacks by using the Self-service user interface.
Enhanced multitenancy
Delegate roles and access to resources among cloud administrator, domain
administrator, service designer, and end user.
Enhanced virtual machines management
Start, stop, resize, images created outside of the IBM Cloud Orchestrator
environment and map them to OpenStack projects from the Self-service
user interface.
Integration with SoftLayer
Extend your cloud to deploy instances and orchestrate resources on
SoftLayer.
New Administration user interface
Manage your virtual infrastructure and user access via the new user
interface.
Enhanced metering capabilities
Exploit OpenStack Ceilometer to collect metering data.
Capability to add custom actions to instances
Add orchestration actions directly to instances.
Enhanced high availability of the IBM Cloud Orchestrator management stack
Enhanced high availability is provided by introducing redundancy and
improved recovery for core software components of the IBM Cloud
Orchestrator management stack.
Built-in orchestration content
IBM Cloud Orchestrator includes content packs that cover the most typical
automation scenarios related to infrastructure-as-a-service and
platform-as-a-service scenarios.

Product architecture
IBM Cloud Orchestrator is a comprehensive product that integrates the capabilities
of several other IBM solutions.
The main components of IBM Cloud Orchestrator are the process engine and the
corresponding modeling user interface, which is used to create processes. For this
purpose, IBM Cloud Orchestrator uses the capabilities of IBM Business Process
Manager. It also integrates other domain-specific components that are responsible
for such functions as monitoring, metering, and accounting. IBM Cloud
Orchestrator bundles all these products and components and provides processes
that are required to implement the domain-specific functionalities.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Cloud Marketplace
Workflow Orchestration

Service Management
- Monitor
- Back up and restore
- Security and patch compliance

Development
tools

Patterns

Software Stacks

Public Cloud
Gateway

Infrastructure-as-a-Service (IaaS)

Storage
(Cinder)

Compute
(Nova)

Network

The following is a description of the role each major component plays in IBM
Cloud Orchestrator:
Infrastructure-as-a-Service
The Infrastructure-as-a-Service (IaaS) component is responsible for
managing access to compute, storage and networking resources in the
virtual environment. All requests to provision services across these services
is performed by this component. The IaaS component is delivered by using
OpenStack, a leading open source, community-driven project for highly
scalable, highly resilient cloud infrastructure management. IBM is one of
the Platinum Members of the OpenStack Foundation.
Software Stacks
While not a specific component itself, Software Stacks represent the
concept that when one or more virtual systems are deployed, it is also
possible to specify multiple software packages to be deployed upon first
boot of those systems. It can be done by invoking simple installation
scripts, but also other strong tools can be used such as Chef recipes and
cookbooks for automated installation and configuration.
Patterns
Patterns allow for deploying more complex middleware configurations and
multinode applications. The Patterns component provides a graphical
editor that allows the user to describe multiple virtual systems, each with a
base image and set of software to be installed, and then specify the
relationships and configuration scripts necessary to connect those systems
together. With this level of automation, an entire multisystem deployment
can be done with just a few simple clicks.
Workflow Orchestration
The Workflow Orchestration component provides a graphical editor that
allows the user to easily customize and extend the procedures that are
followed when a user request is initiated. In addition, it also provides the
facilities to customize the self-service catalog so that users have access to a
variety of service request types that they can access. This component is
delivered by embedding IBM's award-winning Business Process Manager
technology along with a number of pre-built automation toolkits that make
it possible to integrate workflow automation with the cloud platform and
Chapter 1. Overview

its other components. The graphical designer is highly flexible, providing

many integration techniques ranging from invocation of simple scripts and
calling web services to invoking more sophisticated programs such as
those written in Java.
IBM Cloud Orchestrator Catalog
The IBM Cloud Orchestrator Catalog is a publicly accessible website where
various forms of automation can be downloaded and used within IBM
Cloud Orchestrator. It includes references to supported automation
communities such as Chef, ready to use Patterns and Images, and a variety
of pre-built Workflow Orchestration routines, packages and toolkits. It is
designed to "ship when ready", meaning that new automation can become
available at any time, regardless of IBM Cloud Orchestrator release
schedules.
Public Cloud Gateway
The Public Cloud Gateway component is responsible for the integration
with public clouds enabling the complete IT services delivery on resources
running on public clouds such as Amazon EC2, IBM SoftLayer, or not-IBM
OpenStack.
Service Management
This box represents optional additional management functions that are
included in IBM Cloud Orchestrator Enterprise Edition. It also highlights
the ability to integrate through Workflow Orchestration other management
tools and disciplines that may be important within your environment.
Development tools
This box represents the ability to integrate developer tools from IBM
Rational Team Concert and a set of plug-ins within Cloud Continuous
Delivery such as that a user can automate a "continuous delivery pipeline"
from check-in of code, through build, deployment, test, and promotion.
Those tools are not provided within IBM Cloud Orchestrator, but more
information about them can be found on ibm.com.

Product features and components

Read about the main features and components of IBM Cloud Orchestrator.

Delivering pattern-based clouds

IBM Cloud Orchestrator is integrated with Workload Deployer, an advanced
pattern engine. You can use IBM Cloud Orchestrator to design, deploy, and reuse
software solutions (virtual systems, virtual applications, and OpenStack Heat
infrastructural stacks) that are spread across multiple virtual instances with
automatic scalability policies.
IBM Cloud Orchestrator gives you greater flexibility by removing the need to
develop specific interfaces for different cloud services. You can quickly combine
and deploy various cloud services onto the cloud infrastructure by assigning the
compute, storage, and network resources with an easy-to-use graphical interface.
For more information, see Pattern Engines on page 6.

Supporting private, public, and hybrid cloud environments

IBM Cloud Orchestrator is a private cloud offering that significantly simplifies the
task of managing an enterprise-grade cloud. You use a core set of
open-source-based technologies to build enterprise-class cloud services that can be

IBM Cloud Orchestrator 2.4.0.2: User's Guide

ported across hybrid cloud environments. You can use the Public Cloud Gateway
to communicate with SoftLayer, Amazon EC2, and non-IBM-supplied OpenStack.
For more information, see Chapter 8, Managing a hybrid cloud, on page 661.
The supported hypervisors are:
v In Heat: VMware, KVM, z/VM, PowerVC, Hyper-V.
v In Hybrid: EC2, NIO, SoftLayer.

Designing business processes

IBM Cloud Orchestrator is integrated with IBM Business Process Manager, a
workflow engine with graphical tooling. You can extend the capabilities of IBM
Cloud Orchestrator by using the simple drag-and-drop technology in Business
Process Manager to create and edit complex workflows: you can design, run,
monitor, and optimize business processes. For more information, see Custom
extensions on page 11.

Promoting open-source technology

IBM Cloud Orchestrator is based on the open-source OpenStack software.
OpenStack is a collection of open source technologies that provide scalable
computing software for both public and private clouds. For detailed information
about OpenStack, see the OpenStack documentation.For more information, see
Overview of OpenStack on page 8.

Administering the cloud infrastructure

Administrators can use the Administration user interface, which is based on
OpenStack Horizon technology, to easily manage and monitor the cloud
infrastructure. Administrators can define networks and flavors; inspect the actual
resource consumption; and manage users, roles, and projects. For more information
about using the Administration user interface, see Administering as cloud
administrator on page 261.

Customizing the Self-Service Catalog

The intuitive Self-service user interface provides users with a customizable catalog
of offerings. The offerings can be grouped into categories that are created by
administrators to suit the needs of the work environment. For more information
about self-service, see Designing self-service on page 324.

Storing persistent data

An IBM DB2 database is used to store all the IBM Cloud Orchestrator persistent
data. OpenStack services, Workload Deployer, and Business Process Manager use
this database. A DB2 instance is also used by the deployment server to store
installation and configuration data.

Ensuring high availability

IBM Cloud Orchestrator provides high availability to help to reduce the downtime
of the management stack. In addition, operation of the IBM Cloud Orchestrator
management stack is simplified. For more information, see Managing high
availability on page 235.

Chapter 1. Overview

Supporting TOSCA
IBM Cloud Orchestrator supports importing, deploying, and exporting service
templates according to the OASIS Topology and Orchestration Specification for
Cloud Applications (TOSCA). This support enables the consumption of third-party
content provided in a standardized format.

Managing cost
The IBM SmartCloud Cost Management component of the Enterprise Edition
provides functionality for collecting, analyzing, reporting, and billing that is based
on usage and costs of shared computing resources. With this tool, you can
understand your costs and track, allocate, and invoice based on allocated or actual
resource use by department, user, and many more criteria. For more information
about cost management, see Metering and billing.
Within IBM Cloud Orchestrator, metering is primarily driven from the OpenStack
layer to capture all virtual machine provisioning requests. For more information,
see the OpenStack Collector topic.

Monitoring
In the Enterprise Edition of IBM Cloud Orchestrator, you can monitor workloads
and instances using IBM Tivoli Monitoring. With this component, you can
measure the cost of cloud services with metering and charge-back capabilities. For
more information about monitoring, see Integrating with IBM Tivoli Monitoring
on page 717.

Pattern Engines
Learn about the different IBM Cloud Orchestrator pattern engines and determine
which one is more appropriate for your environment.

OpenStack Heat
OpenStack Heat templates are suitable for scenarios that focus on the
infrastructure. You can create resources such as instances, networks, volumes,
security groups, users, and floating IP addresses, and define the relationships
between these resources (for example, a volume must be attached to a specific
instance, some instances are to be connected using this network, and so on). It
allows the addition of auto-scaling services integrated with OpenStack Ceilometer.
Even though OpenStack Heat can be integrated with Puppet or Chef it is not the
recommended engine to create patterns in which software installation and
configuration are crucial. Images to be deployed via Heat templates require that
cloud-init be installed. For more information about OpenStack Heat, see
Working with Heat templates and stacks on page 317.

Virtual System Patterns (classic)

Virtual System Patterns (classic) are used for backward compatibility with
SmartCloud Orchestrator 2.3. You can deploy multiple instances by adding
network interfaces, volumes, users, and groups. You can add and configure
software at deployment time. Images to be deployed via virtual system patterns
(classic) require the activation engine to be installed. Images that are purchased
from IBM Cloud Orchestrator Catalog can also be used. For more information, see

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 7, Managing and deploying virtual patterns, on page 353, and Chapter 6,
Managing virtual images, on page 331.

Virtual System Patterns and Virtual Application Patterns

These patterns provide the same functions as the Virtual System Patterns (classic),
enhanced with the possibility of defining scaling policies based on resource
consumption in the instances, routing policies for HTTP/HTTPs ports, and security
policies to disable root ssh access. You can serialize and order software installation
and configuration steps across multiple instances. These steps can include
operating system reboots. Images to be deployed via Virtual System Patterns and
Virtual Application Patterns require that cloud-init and other software
prerequisites be installed. For more information, see Chapter 7, Managing and
deploying virtual patterns, on page 353, and Chapter 6, Managing virtual
images, on page 331
The following table explains the differences between the different deployment and
pattern engines.
Table 1.
Single Server - Nova Stacks - Heat

Patterns - Workload
Deployer

Complexity

Small

Medium

Large

Purpose

Provision a single
virtual machine

Provisions multiple
Provisions multiple
virtual machines with virtual machines with
network and storage network, storage and
additional software

Capabilities

v user id and
password or ssh
key

v input yaml file

v graphical editor

v image and flavor

v user id and
password or ssh
key

v define
dependencies and
order

v region and
availability zone

v lookup of input
parameters

v add software
bundles

v network

v add network and

storage

v add script
executions

v details view

v details view

v start and stop

v delete

v graphical details
view

v delete

v start and stop

v execute script

v single VM actions
for parts

v custom actions

v custom actions

v run user actions

Actions

v delete
v custom actions

Supported
Hypervisions

All

All, except Public

Cloud Gateway

All

Chapter 1. Overview

Overview of OpenStack
IBM Cloud Orchestrator is based on OpenStack (the Icehouse release).
OpenStack is a collection of open source technologies that provide scalable
computing software for both public and private clouds. For detailed information
about OpenStack, see the OpenStack documentation. For a list of the OpenStack
services, refer to Overview of OpenStack.
IBM Cloud Orchestrator uses the following components and services of OpenStack:
Ceilometer
Collects metering data related to CPU and networking.
Image (codenamed Glance)
Provides a catalog and repository for virtual disk images. The virtual disk
images are mostly used in the OpenStack Compute service component.
Compute (codenamed Nova)
Provides virtual servers on demand.
Identity (codenamed Keystone)
Provides authentication and authorizations for all OpenStack services.
Block Storage (codenamed Cinder)
Provides persistent block storage to guest virtual machines.
Network (codenamed Neutron)
Provides network management.
Dashboard (codenamed Horizon)
Provides a web-based user interface.
Orchestration (codenamed Heat)
Provides an engine to launch multiple composite cloud applications based
on templates.
To configure and administer IBM Cloud Orchestrator, use the OpenStack
command-line interface or the Admin Console. For example, you might need to
use the keystone command-line interface to manage authentication and
authorizations, and the glance command-line interface to manage virtual images.
For more information about the OpenStack command-line interface, see the
OpenStack CLI Guide.

Multitenancy overview
This section describes the roles and delegation in IBM Cloud Orchestrator.
Delegation means that a more powerful role can delegate certain tasks to a less
powerful role. It includes two different types of persona:
Service provider
Is responsible to host IBM Cloud Orchestrator and provide the cloud
infrastructure and services.
Service consumer
Consumes services from the service provider and acts only in the context
of the tenant.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Service Provider

Customer (Tenant)

Cloud Admin
Domain Admin
Onboard a new domain
(tenant, LOB, department),
grant AZ to domain, and
define quota

Catalog Editor
Onboard users in a domain
(tenant) and configure projects

Populate the self-service

catalog to deploy a VM

End User

Request VM via
Self-Service UI and
run script

Inherit the functionality, for example Cloud Admin can do the same tasks as the Domain Admin

IBM Cloud Orchestrator provides different user interfaces that are optimized for
the user experience of a specific role. The following user interfaces exist:
Administration user interface
Only used by a Cloud Administrator. The user interface is based on
OpenStack Horizon and allows the configuration of the cloud
infrastructure and identities. The view shows the resources in the context
of a selected region.
IBM Process Designer and IBM Business Process Manager
Is only used by cloud administrators and content developers. It is the main
user interface to develop new toolkits and catalog content like processes
and human services. It can be used to load new content from the IBM
Cloud Orchestrator Catalog.
Self-service user interface
Is mainly used by tenant users, like domain administrator, catalog editors
and end users. It provides a self-service portal with dashboard, self-service
catalog and managing instances owned by the user. It further support
configuration of the domain and catalog content, and a bandwidth of
panels to manage patterns including a graphical editor.
User interfaces are used by the different personas. The following list explains the
roles, starting from the most powerful,Cloud Administrator, to the most restrictive,
End User:
Cloud Administrator (Service provider)
The Cloud Administrator is the most powerful role who can manage and
administer the whole cloud infrastructure resources, identities, self-service
catalog and its artifacts across all tenants. A special persona of the Cloud
Administrator is the content developer who implements content packs,
processes and coaches that implement the offerings. The Cloud
Administrator can delegate certain tasks, like user, project, pattern, and
catalog configuration to the Domain Administrator.
Domain Administrator (Service consumer)
The Domain Administrator is the most powerful role within a tenant but
less powerful than the Cloud Administrator. The Domain Administrator is
responsible to setup users, projects, patterns, and self-service catalog
content in the domain. However the Domain Administrator can only rely
on resources that are assigned to the domain by the Cloud Administrator.
The Domain Administrator can delegate certain tasks like pattern and
self-service catalog configuration to the catalog editor.
Chapter 1. Overview

Catalog Editor (Service consumer)

The catalog editor (or Service Designer) is responsible for creating patterns
in the cloud and configuring the self-service catalog for users and projects
in the domain. The catalog editor relies on the content packs that are
exposed to the domain by theCloud Administrator. For example, the
catalog editor can create patterns, implement script packages and define
software packages that are deployed with the pattern. It then exposes the
patterns via offerings in the service catalog, which are then used by the
End User.
End User (Service consumer)
The End User can request service like virtual machines, pattern instances
and stacks, from the self-service catalog. The End User can also work with
the instances, like start, stop virtual machine or install software on virtual
machine. Furthermore, the End User can view the dashboard and can work
on inbox assignments. The End User always works on-behalf-of a project.
Custom (Service consumer)
A role with same rights as the End User. The service provider can decide
to implement an approval process for customers and could introduce the
role Approver. The content packs could then use the Approver role to
assign any approval request to users with that role. However, it would still
be in the responsibility of the Domain Administrator to decide which user
is the approver of a project.
For more information about the role of the Cloud Administrator, see the following
topics:
v Chapter 2, Installing, on page 15
v
v
v
v

Chapter 3, Administering, on page 221

Chapter 10, Reporting, on page 733
Metering and billing
Chapter 12, Troubleshooting, on page 1025

For more information about the responsibility of the Domain Administrator, see
Administering as domain administrator on page 274
For more information about the role of service designers, see the following topics:
v Chapter 4, Managing orchestration workflows, on page 293
v Chapter 5, Working with self-service, on page 309
v Chapter 6, Managing virtual images, on page 331
v Chapter 7, Managing and deploying virtual patterns, on page 353
v Chapter 11, Reference, on page 735
For more information about the role of an End User, see Using self-service on
page 309.

10

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Custom extensions
You create custom extensions to IBM Cloud Orchestrator in the Business Process
Manager Process Designer tool and base them on Business Process Manager
business processes. To implement user interface extensions, you can use Business
Process Manager human services.
IBM Cloud Orchestrator delivers a set of Business Process Manager toolkits that
cover the most common automation scenarios in the infrastructure-as-a-service and
platform-as-a-service environments. Each toolkit provides a set of reusable artifacts:
Business processes
A business process is any course of action or procedure that an
organization follows to achieve a larger business goal. When you break it
down, a business process is actually a series of individual tasks or
activities that are performed in a specific order. Business processes provide
the primary means through which enterprise services are integrated.
Services
Services provide functions for a business process, which itself is a sequence
of services. Creating services separately from a business process means a
service can be developed independently of a business process and that
many types of business processes can reuse that service.
Human services
Human service includes an activity in your business process definition that
creates an interactive task that process participants can perform in a
web-based user interface.
Coaches
Coaches are the user interfaces for human services.
Business object definitions
Business objects carry the functional properties, data transformation
information, and file content that the adapter needs to process requests and
generate responses.
With the help of these artifacts, you can efficiently build custom extensions for IBM
Cloud Orchestrator. The provided toolkits also contain numerous samples that
show how to define custom extensions.
You can download more Business Process Manager toolkits from the IBM Cloud
Orchestrator Catalog. These toolkits provide more content for different areas, such
as networking or storage, and you can also use them to build IBM Cloud
Orchestrator extensions.
Restriction: If you define more than one snapshot for Business Process Manager
process application or toolkit, you will be able to use only the artifacts of the top
level to define a new extension in IBM Cloud Orchestrator.

Chapter 1. Overview

11

Deployment modes
IBM Cloud Orchestrator supports several deployment modes on a variety of
hypervisor types.
IBM Cloud Orchestrator supports deployment in Demo, Distributed, and
High-Availability Distributed modes. Optionally, you can also deploy OpenStack
Neutron and an external IBM DB2 database.
IBM Cloud Orchestrator introduces a new deployment topology to make the
management stack highly available. The High-Availability Distributed topology
provides redundancy and improved recovery for core software components of the
IBM Cloud Orchestrator management stack. The key benefit of the new
High-Availability Distributed topology is a reduction of unplanned and planned
downtimes. The new topology ensures that, in certain failure situations, the
processing of the IBM Cloud Orchestrator management stack is not interrupted,
and incoming deployment requests can be processed even though some
components of the cloud management stack failed. Examples include the
introduction of application clustering for IBM Business Process Manager,
OpenStack Keystone, and many other OpenStack components. In addition, an
improved recovery approach is introduced by using classic high-availability
clustering. This approach is especially useful for software components that cannot
run in an Active-Active setup, but allow classic failover scenarios. Another key
benefit of the new High-Availability Distributed deployment topology is improved
performance. Core IBM Cloud Orchestrator components run in an Active-Active
setup, which improves throughput. The High-Availability Distributed topology is
installed through the IBM Cloud Orchestrator Deployment Service. The
Deployment Service automates most parts of the high-availability installation, and
configuration is fully automated, which reduces and simplifies the overall
installation process for the IBM Cloud Orchestrator administrator.
For more information about these deployment modes, see Deployment
topologies on page 16.
IBM Cloud Orchestrator supports the following hypervisor types: KVM, VMware,
Hyper-V, PowerVC, and z/VM.
Amazon EC2 and SoftLayer are supported via the Public Cloud Gateway. For more
information, see Chapter 8, Managing a hybrid cloud, on page 661.
IBM Cloud Orchestrator Enterprise Edition provides additional capabilities from
IBM Tivoli Monitoring and IBM SmartCloud Cost Management. For more
information about these products, see Integrating with IBM Tivoli Monitoring on
page 717 and Metering and billing.

IBM Platform Resource Scheduler overview

Platform Resource Scheduler integrates IBM OpenStack with Enterprise Grid
Orchestrator (EGO).
OpenStack is used to provision VM instances. EGO is used to schedule resources
for OpenStack to make decisions on where to deploy the VM instance with
specified resource selection criteria, such as migrating, resizing, and powering on.

12

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Platform Resource Scheduler is an optional add-on to IBM Cloud Orchestrator and

it is not shipped as part of IBM Cloud Orchestrator but it must be obtained
through IBM separately.
To use Platform Resource Scheduler with IBM Cloud Orchestrator, first
install IBM Cloud Orchestrator, then contact IBM to obtain and install Platform
Resource Scheduler with a 90 day evaluation license. To use Platform Resource
Scheduler in production, contact IBM to purchase a full license.
To install Platform Resource Scheduler, use the Platform Resource Scheduler
installation instructions.
Once installed, you can learn more about Platform Resource Scheduler and start to
use it.

Chapter 1. Overview

13

14

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 2. Installing
Follow this procedure to install IBM Cloud Orchestrator.

Planning your installation

Before you start the installation, review the requirements and plan the whole
process.

Installation overview
Get familiar with the basic concepts of the IBM Cloud Orchestrator installation
topology so that you can plan your installation.
The main components of an IBM Cloud Orchestrator installation topology are:
Deployment Server
Hosts the Deployment Service that is the deployment management
component to deploy an IBM Cloud Orchestrator environment with a
predefined topology by using the related deployment templates.
Central Servers
Host the core IBM Cloud Orchestrator management components.
Region Servers
Are the components used to communicate with a specific hypervisor
management infrastructure (KVM, VMware, Hyper-V, PowerVC, or z/VM).
The KVM region server requires one or more KVM compute nodes to
provide the compute resources. The VMware Region server needs to
connect to existing VMware Virtual Center to provide virtual machines.
The Hyper-V region server requires one or more Hyper-V compute nodes
to provide the compute resources.The PowerVC region server requires to
connect to existing PowerVC to provide virtual machines. The z/VM
region server needs to connect to xCat management Node on z/VM to
provide virtual machines.
KVM or Hyper-V Compute Nodes
Are the components used to manage the virtual machines through the
interface provided by KVM or Hyper-V.
The first step in the installation procedure is to install the Deployment Service.
Then, you install the Central Servers and, as last step, you set up the Region
Servers.
Depending on your needs and the available hardware resources, using the
predefined topology templates you can set up one of the following environments:
v A demo environment
v An environment with management components spread across multiple nodes
v An environment with management components spread across multiple nodes
and high availability
After the deployment, you can also use the Deployment Service to manage your
environment in terms of update, scale out, or delete. Additional Region Servers can
be added to enable a multiple-region environment.
Copyright IBM Corp. 2013, 2015

15

Deployment topologies
Before you start to deploy IBM Cloud Orchestrator, you must decide which
deployment topology to install for the IBM Cloud Orchestrator management stack.
IBM Cloud Orchestrator supports the following deployment topologies:
v Demo topology
v Distributed topology
v High-Availability Distributed topology
The first step for each deployment topology is to install the Deployment Service on
a dedicated system. The descriptions of the IBM Cloud Orchestrator topologies
below do not mention the Deployment Service. The topology descriptions in this
topic focus only on the specific IBM Cloud Orchestrator components.

Demo topology
This topology is the simplest topology, and it is suitable for demo and
proof-of-concept scenarios. The Demo topology requires minimal resources, and
does not use Neutron networking or high-availability features. The Demo topology
supports a single VMware or KVM region only, it does not support more than one
region. The Demo topology is also known as the all-in-one topology.
Database

IBM HTTP
Server

Self-Service
UI

OpenStack
Nova

OpenStack
Glance

OpenStack
Ceilometer

Public Cloud
Gateway

Administration
UI

OpenStack
Cinder

OpenStack
Heat

Business
Process
Manager

OpenStack
Keystone

qpid

Central Server 1

Workload
Deployer

Central Server 2

The Demo topology involves two systems:

v The first system acts as both Central Server and Region Server. It hosts the IBM
HTTP Server, Business Process Manager, the Self-service user interface, the
Administration user interface, all the OpenStack components, qpid, and the
Public Cloud Gateway. You can install the database on this system or you can
use an external database as described in Configuring an external database on
page 40.
v The second system hosts the Workload Deployer component.

Distributed topology
This topology is typically used for environments in which you can use all the
product features, but do not want to invest in resources for high availability. IBM
Cloud Orchestrator components are installed on three Central Servers. It supports
one or more Region Servers and it supports one or more OpenStack Neutron
servers.

16

IBM Cloud Orchestrator 2.4.0.2: User's Guide

OpenStack
Glance

Administration
UI

OpenStack
Cinder

OpenStack
Heat

OpenStack
Keystone

qpid

IBM HTTP
Server

Self-Service
UI

OpenStack
Ceilometer

Public Cloud
Gateway
Business
Process
Manager

Central Server 1

Workload
Deployer

OpenStack
Nova

Database

Central Server 2

Central Server 3

Region Server

OpenStack
Neutron

Neutron Server

Central Server 1 hosts the database and OpenStack Ceilometer. You can install the
database on this system or you can use an external database as described in
Configuring an external database on page 40.
Central Server 2 hosts the IBM HTTP Server, Business Process Manager, the Public
Cloud Gateway, the Self-service user interface, the Administration user interface,
and OpenStack Keystone.
Central Server 3 hosts the Workload Deployer component.
Each region server hosts OpenStack Nova, Glance, Cinder, Heat, and qpid. If you
want to use OpenStack Neutron features, you must install OpenStack Neutron on a
dedicated system.
Note: The keystone CLI is always installed on the same system where OpenStack
Keystone is installed. All of the other OpenStack CLI commands are available on
the Region Server.

High-Availability Distributed topology

This topology is the most advanced topology for the IBM Cloud Orchestrator
management stack. It provides improved availability of the IBM Cloud
Orchestrator management stack by removing single points of failure (SPOF) for
various components. This improvement is achieved by application clustering (for
example, Business Process Manager cluster or Keystone cluster). Also, on certain
systems, a high-availability cluster solution is automatically installed and
configured to provide automated failover of failed components (for example,
high-availability clustering for the haproxy load balancer). Furthermore, System
Automation Application Manager is installed on a separate server to automatically
restart failed components. System Automation Application Manager also improves
startup and shutdown times for the IBM Cloud Orchestrator management stack by
running the start or stop sequences in parallel.
For the High-Availability Distributed topology, you must install an external
database as described in Configuring an external database on page 40. It is
advisable to set up an IBM DB2 database with a high-availability solution because
the database is a core component of the IBM Cloud Orchestrator management
stack.

Chapter 2. Installing

17

OpenStack
Ceilometer

Central Server 1

Database

ExternalDB
Server

Workload
Deployer

OpenStack
Nova

OpenStack
Glance

Administration
UI

OpenStack
Cinder

OpenStack
Heat

Business
Process
Manager

OpenStack
Keystone

qpid

haproxy

Tivoli
System
Automation

haproxy

IBM HTTP
Server

Self-Service
UI

Public Cloud
Gateway

Central Server 2

Central Server 3
System
Automation
Application
Manager

Tivoli
System
Automation

Region Server

OpenStack
Nova

OpenStack
Glance

Administration
UI

OpenStack
Cinder

OpenStack
Heat

OpenStack
Keystone

qpid

Tivoli
System
Automation

haproxy

IBM HTTP
Server

Self-Service
UI

Public Cloud
Gateway
Business
Process
Manager

Central Server 2'

SAAM Server

OpenStack
Neutron

Neutron Server

Tivoli
System
Automation

Region Server'

The Central Server setup consists of the following systems:

v Central Server 1 hosts OpenStack Ceilometer.
v Central Server 2 hosts the IBM HTTP Server, Business Process Manager, haproxy,
the Public Cloud Gateway, the Self-service user interface, the Administration
user interface, Tivoli System Automation, and OpenStack Keystone.
v Central Server 2' acts as backup system of Central Server 2 and it hosts the IBM
HTTP Server, Business Process Manager, haproxy, the Self-service user interface,
the Administration user interface, Tivoli System Automation, and OpenStack
Keystone.
v Central Server 3 hosts the Workload Deployer component.
An additional system is needed to run System Automation Application Manager.
The Region Server setup consists of two or three systems:
v Two systems for the high-availability setup of the core region components (for
example, nova-api, glance-api, and others). Each region server hosts OpenStack
Nova, Glance, Cinder, Heat, and qpid. Region Server' acts as backup system of
Region Server.
v If you want to use OpenStack Neutron features, you must install OpenStack
Neutron on a dedicated system. The Neutron Server is not configured as highly
available.
[VMware only:] If you are using VMware as the hypervisor to host the IBM Cloud
Orchestrator environment, you can integrate the VMware high-availability features
with the high-availability features provided by System Automation Application
Manager and Tivoli System Automation.
Note: The keystone CLI is always installed on the same system where OpenStack
Keystone is installed. All of the other OpenStack CLI commands are available on
the Region Server.

18

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Hardware prerequisites
The hardware prerequisites are based on the role of the node you are using to
deploy the IBM Cloud Orchestrator.
Table 2. Hardware prerequisites

Machine
Role

Processor
(vCPU)

Memory
(GB)

Overall free
volume
requirements
(GB)
/

Deployment
Server

117

15

22

43

Central
Server 1

115

75

20

10

Central
Server 2

96

40

30

20

Central
Server 3

146

77

KVM Region
Server

77

40

30

KVM
Compute
Node

32

160

80

70

VMware
2
Region Server

77

40

30

Hyper-V
2
Region Server

77

40

30

2
Power
Region Server

77

40

30

z/VM Region 2
Server

77

40

30

Neutron
Server

32

20

Server for
4
all-in-one
deployment
with KVM
Region (demo
topology)

16

350

200

20

30

40

30

30

4
Server for
all-in-one
deployment
with VMware
Region (demo
topology)

16

377

216

22

32

43

32

32

Server for
System
Automation
Application
Manager

50

15

15

10

10

Free space in directories (GB)

/home

/opt

/var

/tmp

/data
27

/drouter

54

Disk planning considerations:

Chapter 2. Installing

19

v The specified hard disk space is the minimum free space required on the
machine before the IBM Cloud Orchestrator installation. Be sure that there is
sufficient space for the required partitions.
v For the Deployment Service node, additional disk space (about 14 GB) is
required to store the IBM Cloud Orchestrator packages. If you plan to install
IBM Cloud Orchestrator as highly available, you need 40 GB to store all of
the IBM Cloud Orchestrator packages, including the additional high-availability
packages.
v For Central Server 1, additional space might be required on the /home partition
after a period of time, depending on database size. Monitor the partition size.
Use LVM to manage the partition so that you can extend the size if required.
v For Central Server 3, the /drouter directory is used to store the contents (images
and patterns) of the Workload Deployer component. Increase the partition size
as necessary to match the contents that you want to deploy.
v For a KVM Compute node, the virtual machine master images and the virtual
machine ephemeral disks are located in the /var/lib/nova directory by default.
Plan the required disk space for this directory accordingly.
For the Demo topology, in addition to the server for all-in-one deployment, only
one central server is needed. This central server, where the Workload Deployer
component is installed, must satisfy the Central Server 3 hardware requirements.
For more information about the demo topology, see Deployment topologies on
page 16.
For more information about hardware requirements for the System Automation
Application Manager server, see the Tivoli System Automation Application
Manager V4.1 documentation at http://www-01.ibm.com/support/
knowledgecenter/SSPQ7D_4.1.0/com.ibm.saam.doc_4.1/welcome_saam.html.
For a Neutron Server or KVM Compute Node, use a physical server for better
performance.
You must configure a different Neutron Server for each Region Server that uses a
Neutron network.
For an IBM Cloud Orchestrator environment with high availability configuration,
you must configure a secondary Central Server 2 and a secondary Region Server
(for each primary Region Server in your environment) with the same prerequisites
specified in the previous table. Create these secondary virtual servers on a different
physical host than the primary virtual servers, to ensure that the IBM Cloud
Orchestrator management stack remains available if the primary host fails.
Restriction: For a high-availability installation, only VMware and KVM regions are
supported.

20

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Software prerequisites
Review the software prerequisites for your environment.
IBM Cloud Orchestrator runs on Red Hat Enterprise Linux.
The installer must access one of the following Red Hat Enterprise Linux
repositories:
v Registered Red Hat Network
v Customer-provided yum repository
v Red Hat Enterprise Linux ISO
Note: Before you install the product:
v For highly-available installation: to specify that the load-balancer repository for a
specific system should be managed by Red Hat Network, complete the following
steps:
1. In the Red Hat Network interface, click the Systems tab.
2. Select the system.
3. Click Software > Software Channels.
4. In the Software Channel Subscriptions list, ensure that the RHEL Server
Load Balancer channel option is selected.
v Ensure that the /etc/yum.repos.d/ds.repo file does not exist on the Deployment
Server.
Note: If there is already an operating system yum repository configured on the IBM
Cloud Orchestrator node, the Deployment Service will not provide its internal yum
repository to the node. If there is no operating system yum repository configured in
the IBM Cloud Orchestrator node, the Deployment Service will provide its own
yum repository as the node yum repository. In the failure case, the Deployment
Service provides a Red Hat 6.4 yum repository to the Neutron node which actually
requires the Red Hat 6.5 package. The solution to this issue is to manually provide
a Red Hat 6.5 operating system repository to the Neutron node before deploying
the IBM Cloud Orchestrator node.

Manage-from requirements
IBM Cloud Orchestrator services can be installed on KVM or VMware virtual
machines, or on physical machines.
Depending on the deployment scenario that you choose, the Deployment Service
uses already existing virtual images or it creates them and then installs the
software stack on them.
If you want the Deployment Service to create the virtual machines, ensure that the
virtualization technology (VT) is enabled on the operating system that is running
the Deployment Service.
The following table describes the host and guest operating systems supported for
installing IBM Cloud Orchestrator.

Chapter 2. Installing

21

Table 3. Host and guest operating systems supported by the standard installation
Hypervisor

Host operating system

Guest operating system

Reference

KVM

Red Hat Enterprise Linux 6.4,

6.5, or 6.6 x86_64

Red Hat Enterprise Linux 6.4,

6.5, or 6.6 x86_64

Managing guests with the

Virtual Machine Manager
(virt-manager)

VMware

VMware vCenter Server 5.0,

5.1, 5.1 u2, 5.5, 5.5 u1 or 5.5 u2
VMware vSphere 5.0, 5.1, 5.1
u2, 5.5, or 5.5 u1

vSphere Virtual Machine

Administration

Note:
v Be sure that all the IBM Cloud Orchestrator central servers run the same Red
Hat Enterprise Linux version.
v VMware Tools must be installed on all the VMware virtual machines where you
install IBM Cloud Orchestrator.
v If you want to use Red Hat Enterprise Linux 6.6 as guest operating system on
VMware, VMware vCenter Server must be at least version 5.0 u3.
v If you want to use OpenStack Neutron, the server that hosts the Neutron service
must run Red Hat Enterprise Linux 6.5 and iproute must be upgraded to the
version 2.6.32-130. The iproute-2.6.32130.el6ost.netns.2.x86_64.rpm package can be downloaded from
http://repos.fedorapeople.org/repos/openstack/openstack-icehouse/epel-6/.
For this case, it is recommended that all other IBM Cloud Orchestrator servers
also run Red Hat Enterprise Linux 6.5. If you have IBM Cloud Orchestrator
servers run Red Hat Enterprise Linux 6.4 except the Neutron server, ensure that
the Neutron server has its own yum repository well configured with Red Hat
Enterprise Linux 6.5.
v If you plan to use an existing external database, Red Hat Enterprise Linux 6.4,
6.5, or 6.6 64 bits must be installed on the database system and you must use
DB2 10.5.
v If you migrated from SmartCloud Orchestrator 2.3 and you were using VMware
4.1, you must upgrade to VMware 5.0 or later before using IBM Cloud
Orchestrator 2.4 or later.
You must apply the following configurations to the IBM Cloud Orchestrator
servers:
v The operating systems must be installed at least with the basic server package
group.
v The bind-utils rpm must be installed.
The python-ldap-2.3.10-1.el6.x86_64 rpm must be installed.
The SSH daemon must be enabled.
The network interface must be configured to use static IPs.
All the IBM Cloud Orchestrator servers must have network connectivity, be in
the same network, and have the network interface used as management network
with the same name (for example, eth0).
v Host name resolution must work across all of the IBM Cloud Orchestrator
servers. You can configure the IBM Cloud Orchestrator servers with the
corporate DNS. If no corporate DNS is available, you must update the
/etc/hosts file on each of the required IBM Cloud Orchestrator servers (for
example, Central Servers, Region Servers, compute nodes) to include all of the
IBM Cloud Orchestrator server hosts. Each entry in the /etc/hosts file should
v
v
v
v

22

IBM Cloud Orchestrator 2.4.0.2: User's Guide

specify both the fully qualified domain name and the host name, in that order.
To verify that you configured the /etc/hosts file correctly, run the following
commands:
host <IP_address>
This command must return the FQDN of the server (for example,
central_server_2.subdomain.example.com).
hostname --fqdn
This command must return the same FQDN as in the previous
command.
hostname
This command must return the first part of the FQDN, that is the host
name (for example, central_server_2).

Manage-to requirements
The following table describes the host and guest operating systems supported by
each type of hypervisor in an IBM Cloud Orchestrator environment.
Table 4. Host and guest operating systems supported by the hypervisors
Hypervisor

Host operating system

Guest operating systems of deployed virtual machines

KVM

Red Hat Enterprise Linux 6.4, 6.5, or

6.6 x86_64

VMware

VMware vCenter Server 5.0, 5.1, 5.1

u2, 5.5, 5.5 u1 or 5.5 u2
VMware vSphere 5.0, 5.1, 5.1 u2, 5.5,
or 5.5 u1

Hyper-V

Windows Server 2012 R2, Standard

edition or Datacenter edition, with
Hyper-V role enabled

SUSE Linux Enterprise Server 11 SP1, SP2, or SP3, 32-bit

or 64-bit
Red Hat Enterprise Linux 5.x, Red Hat Enterprise Linux
6.1, 6.2, 6.3, 6.4, 6.5, or 6.6 32-bit or 64-bit
CentOS 6.3 or 6.4, 64-bit
Windows 2008 R2 64-bit, Windows 7 64-bit, Windows
Server 2012 64-bit, Windows Server 2012 R2 64-bit,
Windows 8 64-bit

PowerVC

IBM Power Virtualization Center

(PowerVC) Standard Edition V1.2.1
Fix Pack 2

AIX 6.1 TL9 or later, AIX 7.1 TL3

Red Hat Enterprise Linux 5.9 or later, Red Hat
Enterprise Linux 6.4 or later, Red Hat Enterprise Linux
7.0
SUSE Linux Enterprise Server 11 SP3

z/VM

IBM z/VM V6.3

Red Hat Enterprise Linux 6.3, 6.4, 6.5, or 6.6

SUSE Linux Enterprise Server 11.1

Note:
v If you migrated from SmartCloud Orchestrator 2.3 and you were using VMware
4.1, you must upgrade to VMware 5.0 or later before using IBM Cloud
Orchestrator 2.4 or later.
v To allow IBM Cloud Orchestrator to connect to VMware vCenter, PowerVC, or
z/VM, you must use an account with specific privileges. For VMware vCenter,
the list of minimum permissions is available at http://docs.openstack.org/
trunk/config-reference/content/vmware.html.
v For z/VM 6.3 systems, you must install the PTFs listed at:
http://www.vm.ibm.com/sysman/xcmntlvl.html
http://www.vm.ibm.com/sysman/osmntlvl.html
v z/VM Single System Image (SSI) configuration is not supported in IBM Cloud
Orchestrator.

Chapter 2. Installing

23

v CentOS is supported only for Virtual System Pattern (Classic) when the images
are prepared using the Image Construction and Composition Tool tool that was
provided with SmartCloud Orchestrator V2.3.
v Images for Linux on System z cannot be used for Virtual System Pattern
(Classic). To deploy a z/VM pattern, you must use the generic OpenStack Image
- Linux [s390x] image to create a Virtual System Pattern.
v PowerVC Express Edition is not supported.
v PowerVC Region Servers do not support secure connections to PowerVC servers
with mixed-case or uppercase host name. For more information, see
Troubleshooting PowerVC region on page 1056.
v PowerVC V1.2.1.2 users must install an interim fix, which is shipped with IBM
Cloud Orchestrator, to ensure that the Workload Deployer component works
correctly. For more information, see Applying interim fix 1 to PowerVC 1.2.1.2
on page 50.
v The Workload Deployer component is not supported on Power6 or Power6+
systems. If you want to use Power6 or Power6+ technology, you can use Heat
templates or the Nova API to deploy servers.

Planning networks
IBM Cloud Orchestrator supports Nova networks and Neutron networks.
You can use Nova networks and Neutron networks in one or more different
regions, but you cannot use Nova networks and Neutron networks within the
same region.
In Hyper-V, PowerVC, and z/VM regions, you can only use Neutron networks.
Nova networks do not support overlapping IP addresses.
Neutron provides rich and flexible scenarios for end users compared to Nova
network. For example, it supports software defined networks (SDN) via Virtual
Extensible LAN (VXLAN) and it also supports traditional routing accessibility such
as VLAN and FLAT.
Note: You cannot use VXLAN for VMware or Hyper-V managed-to environment.
Prerequisites for Nova networks
v The switch must be configured as trunked to support different VLAN IDs.
v There must be a routable gateway for each VLAN on the router.
v The IP address of the gateway must belong to the subnet that you plan to use.
v If using KVM regions, all the Compute Nodes must use the same interface to
connect to the Region Server (for example, all eth0 or all eth1).
v If the Region Server is a VMware virtual machine, the port group must have the
VLAN ID option set to All (4095).
v VMware Region Servers must be in the same network as all the ESXi servers.
v KVM Region Servers can be in the same network as the Compute Nodes, or in a
different network.
For more information about Nova networks, see Managing Nova networks on
page 88.
Prerequisites for Neutron networks

24

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v The Region Server can be in the same network as the Compute Nodes, or in a
different network.
v The Neutron Server must be in the same network as the Compute Nodes.
v In a VMware region, the port groups are not created by the installer. The name
of the port group must match the label of the network in Neutron.
For more information about Neutron networks, see Managing Neutron networks
on page 93.

Using a virtual machine as a network server

You can install the network server (either Neutron or Nova) on a virtual machine.
The network node must be in the same network as the compute nodes. The same
vNICs must correlate to the same NICs on the compute nodes, as shown in the
following topology diagram.

where:
MGM Hyper
The manage-from hypervisor, which can be either Linux KVM or VMware
ESXi.
Network Node
The Neutron node if you are using Neutron networks, or the Region Server
if you are using Nova networks.
Compute Node
The compute node where the virtual machines are deployed.
Br

Bridge.

Pg

Port group.

eth0/vmnic0
Examples of NIC names.
The following prerequisites must be met:
v For a VMware virtual machine:
The port groups to which the network server connects must have the VLAN
ID option set to All (4095).
The port groups to which the network server connects must be configured to
accept Promiscuous Mode.
All the vNICs of the corresponding port groups must correlate correctly to the
NICs of the compute nodes. For example, the connected port group eth0 of
the network server must be in the same network as the eth0 of the compute
Chapter 2. Installing

25

nodes, the connected port group eth1 of the network server must be in the
same network as the eth1 of the compute nodes, and so on.
The network adapter of the vNIC on the network node must be E1000. If
you use the VMXNET3, you may hit the problem that UDP packets are
dropped from the network node.
v For a KVM virtual machine:
The virtual machine must not be running on a compute node.
All the vNICs of the corresponding bridges must correlate correctly to the
NICs of the compute nodes. For example, the connected bridge eth0 of the
network server must be in the same network as the eth0 of the compute
nodes, the connected bridge eth1 of the network server must be in the same
network as the eth1 of the compute nodes, and so on.
The following limitations apply when you install a network server on a KVM
virtual machine:
VXLAN
The network server must communicate with other compute nodes by using
multicast to transmit overlay packets. If the network server is running as a
virtual machine, it relies on the bridge of its hypervisors to connect
externally. A known issue for the kernel of Red Hat Enterprise Linux V6.5
is related to multicast snooping for bridges: sometimes the multicast
packets cannot be received by the virtual machine. If you see this problem,
run the following command to disable multicast snooping in the kernel:
echo 0 > /sys/devices/virtual/net/BRIDGE-OF-NETWORK-SERVER/bridge/multicast_snooping

where BRIDGE-OF-NETWORK-SERVER is the bridge of the data interface of the

network server.
VLAN All 8021q tagged packets must be transmitted transparently through the
bridge in the hypervisor. If you create a VLAN on the network server with
Neutron or Nova network, you must ensure that the same VLAN devices
are not used on the hypervisor. For example: you create a network with
VLAN 100 with physnet1 (eth0) on the network server. In this case, on the
hypervisor of the network server, do not create VLAN device eth0.100.
You can create VLAN device eth0.100 on other VLANs that are not on the
network server. If you really need the same VLAN to work on the
hypervisor, create a VLAN device based on brX instead of ethX. For
example, use the following command to create br0.100:
vconfig add br0 100

Summary of features and capabilities of a network server:

This table summarizes the features and capabilities of deploying a network server
on a virtual machine or on a physical server.
Table 5. Comparison of network types and hypervisors to deploy network servers

Nova-network
on VMware
virtual machine

26

FLAT

FLATDHCP

VLAN

VXLAN

No (yes only for

systems
upgraded from
SmartCloud
Orchestrator)

No

Yes

No

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 5. Comparison of network types and hypervisors to deploy network

servers (continued)
FLAT

FLATDHCP

VLAN

VXLAN

Neutron on
VMware virtual
machine

Yes

Not applicable

Yes

Yes

Nova-network
on KVM virtual
machine

No (yes only for

systems
upgraded from
SmartCloud
Orchestrator)

No

Yes

No

Neutron on
KVM virtual
machine

Yes

Not applicable

Yes

Yes

Nova-network
on physical
server

No (yes only for

systems
upgraded from
SmartCloud
Orchestrator)

No

Yes

No

Neutron on
physical server

Yes

Not applicable

Yes

Yes

For information about limitations, see Using a virtual machine as a network

server on page 25.

Neutron scenarios
If you use a Neutron network, choose one of the supported scenarios for your
environment.
Neutron supports the following scenarios:
Network Server as a gateway
This scenario is suitable when software-defined networks (SDN) are
required. Another important benefit is that network fencing can be
achieved. In this scenario, virtual machines get their internal IP addresses
from the DHCP service and access internet through the SDN gateway.
Because the virtual machines have only internal IP addresses, the only way
to access them is through floating IP addresses. In this scenario, the
network server provides the following functionality:
v DHCP services for different networks
v A gateway for different networks
v Floating IP addresses to the virtual machines to be accessed
Note:
v This scenario can be implemented by using either VLANs or VXLANs.
v Multiple routers are allowed for different networks.
A Cloud Service Provider (CSP) is one type of customer that can leverage
this Neutron configuration. A CSP usually has to support multiple groups
of end users (tenants). Beyond providing network isolation for the
resources provided to each tenant, a CSP may also need to provide to some
tenants the ability to access these resources from the public internet.
Leveraging the configuration described in this scenario, the CSP is able to
provide private resources to its tenants when they connect to the
Chapter 2. Installing

27

environment via, for example, a VPN connection. This configuration also

allows the CSP to provide internet accessible resources directly to tenants
and their users. An example of the private resources can be a development
or test environment, where a tenant develops a new application, that
should not be accessible directly via the internet. An example of an internet
accessible resource could be an HTTP server hosting the development
project metrics that can be shared with externally interested parties.
Physical routing device as a gateway
This scenario is quite similar to what Nova network provides, that is, you
must plan carefully the overall topology because all the virtual machines
must be able to be accessed by using their internal IP addresses, so VLAN
trunks and gateway must be configured properly on switch and router. In
contrast to the first scenario, the network server in this deployment
provides only DHCP services, you cannot use any routing service or
floating IP, and network fencing (overlapping IP) is not supported. Choose
this scenario when a traditional network for the virtual machines is more
suitable.
Note: You can use VLAN or FLAT network.
A user who wants to create a private cloud based on existing virtual
environments can use the configurations described in this scenario. For
example, an IT Operations team that wants to provide better access,
improve SLAs, and satisfy more dynamic compute demands from different
internal teams can use this configuration. Environments that this simpler
configuration supports usually provide network isolation by using VLANs
and subnetworks for the different tenants (usually internal teams). In most
cases, it is not necessary for these resources to be externally accessible nor
does the environment employ extensive use of Network Address
Translation (NAT) and overlapping IP addresses.
Hybrid SDN plus physical routing
This scenario is a combination of the first and second scenarios that can be
deployed in the same environment. Network servers work as SDN
gateway for some of the networks, and for other networks, physical
devices achieve the routing accessibility. Therefore, you can deploy
complex network scenarios.
Note: Neutron does not support alias interfaces.

Planning PowerVC networks

Use the Administration user interface to define PowerVC networks.
PowerVC networks can be defined either on the PowerVC server directly, or from
the IBM Cloud Orchestrator Administration user interface that manages the
PowerVC region.
The advantages of using the Administration user interface (instead of the PowerVC
server) to create the PowerVC networks are as follows:
Subnet creation
v You can use the Administration user interface to create subnets. If an
existing network is configured on PowerVC and the IP address range
must be specified, you can use the Administration user interface to
delete the existing subnet, and create a new subnet with a refined pool
of IP addresses.

28

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v The PowerVC server does not currently allow a user to configure a

subnet. The PowerVC server automatically creates a subnet that
encompasses the entire IP range. The subnet is not displayed in the
output of the Neutron subnet-list CLI command.
Multitenancy support
v The PowerVC Region Server supports multitenancy. If you want to
configure Virtual LANs that are owned by different tenants, those
Virtual LANs must be managed from the IBM Cloud Orchestrator
PowerVC Region Server.
v The PowerVC server does not provide multitenancy.
PowerVC supports only VLAN-based networking, and does not support DHCP.
The Physical Network parameter must be set to default rather than physnet1.

Preparing for the installation

When you have completed your planning, prepare for the installation by
completing these tasks.

Setting up virtual machines

To use virtual machines to install IBM Cloud Orchestrator, use the following
procedure.

Setting up KVM virtual machines

To set up a KVM virtual machine, install and configure the KVM-related software
on the host system and create the virtual machines as described in the following
procedures. Use the same operating system version on all the virtual machines you
use for installing IBM Cloud Orchestrator.
Prerequisites
v The host machines must use Intel VT or AMD-V chipset supporting
hardware-assisted virtualization.
v Virtualization support must be enabled in the BIOS of your host machine.
v Verify that the processor supports KVM by running the following command on
your host system:
grep -E vmx|svm /proc/cpuinfo

If the command returns output, your system supports KVM.

v The following packages must be installed on the host:
kvm
virt-manager
libvirt
libvirt-python
python-virtinst
tunctl
If the packages are not installed, you can install them by using a Yum repository.
To run the following procedure, you must have access to the Red Hat Enterprise
Linux ISO, but you can use different package repositories.

Chapter 2. Installing

29

1. Configure an ISO repository to be available to your host for downloading the

KVM-related packages. To create a repository using an ISO image, perform
the following steps:
a. For example, if you have your Red Hat Enterprise Linux 6.x ISO image
stored in /opt/RHEL6.x-xxxxxxxx.x-Server-x86_64-DVD1.iso, mount the
ISO image by running the following commands:
mkdir -p /mnt/rhel6
mount -o loop /opt/RHEL6.x-xxxxxxxx.x-Server-x86_64-DVD1.iso /mnt/rhel6

b. Create a repo file in the /etc/yum.repos.d directory and change the base
path to the directory path that you specified in the mount command. For
example, create the /etc/yum.repos.d/DVD.repo file with the following
content:
[RHEL-Repository]
name=RHEL repository
baseurl=file:///mnt/rhel6
enabled=1
gpgcheck=0

2. Install the KVM management packages via yum by running the following
command:
yum install kvm virt-manager libvirt libvirt-python python-virtinst tunctl

Operating system configuration

Before creating the virtual machine, you must apply specific configuration changes
to the host operating system. Run the following procedure using root privileges:
1. Disable NetworkManager by running the following commands:
chkconfig NetworkManager off
chkconfig network on
service NetworkManager stop
service network start

2. Start the libvirtd service by running the following command:

service libvirtd start

3. Create a bridge (br0) based on the eth0 interface by running the following
command on the host:
virsh iface-bridge eth0 br0

If the command fails, you can manually configure the networks by performing
the following steps:
a. Edit your /etc/sysconfig/network-scripts/ifcfg-eth0 file as in the
following example:
DEVICE=eth0
HWADDR=AA:BB:CC:AA:BB:CC
ONBOOT=yes
BRIDGE=br0

b. Edit your /etc/sysconfig/network-scripts/ifcfg-br0 file as in the

following example:
DEVICE=br0
ONBOOT=yes
TYPE=Bridge
BOOTPROTO=none
IPADDR=192.168.1.2
NETMASK=255.255.255.0
GATEWAY=192.168.1.1
STP=on
DELAY=0

c. Restart the network by running the following command:

30

IBM Cloud Orchestrator 2.4.0.2: User's Guide

service network restart

d. You can review your interfaces and bridge by running the following
commands:
ifconfig
brctl show

Creating the virtual machines

Use the virt-manager application to create a KVM virtual machine. The
virt-manager application is a desktop user interface for managing KVM virtual
machines. It uses a GUI-based front end for KVM creation, installation, and
monitoring. It also provides an easy method for adding hardware. Launch
virt-manager and follow the wizard.
If you cannot use the virt-manager application, and you are an experienced KVM
user, you can use the command-line interface to create a KVM virtual machine, as
described in the IBM developerWorks article Creating a KVM virtual machine (CLI
method).
After setting up the KVM virtual machines to install IBM Cloud Orchestrator, start
the virtual machine configuration by following the procedure described in
Preparing the IBM Cloud Orchestrator servers.

Setting up VMware virtual machines

You can use the VMware vCenter server to build the virtual machines. For more
information, see the VMware documentation.
After setting up the VMware virtual machines to install IBM Cloud Orchestrator,
start the virtual machine configuration by following the procedure described in
Preparing the IBM Cloud Orchestrator servers.

Preparing the IBM Cloud Orchestrator servers

Before you start the installation process, you must prepare several virtual machines
or physical machines to install IBM Cloud Orchestrator.

Before you begin

You can use VMware or KVM virtual machines to run the IBM Cloud Orchestrator
management from servers. To manage KVM virtual machines, it is recommended
that you use the virt-manager application. To manage VMware virtual machines, it
is recommended that you use the VMware vCenter application. If you want to use
the VMware high-availability solution in your IBM Cloud Orchestrator
environment, use VMware virtual machines to run your IBM Cloud Orchestrator
environment.
If the virtual machines are already available or you plan to use physical machines,
use the following procedure. If you need to create the virtual machines, use the
procedure described in Setting up virtual machines on page 29.

About this task

Repeat the described procedure for each of the virtual or physical machines to
prepare them for the installation process.

Chapter 2. Installing

31

Procedure
1. Make sure that the machines meet the hardware prerequisites described in
Hardware prerequisites on page 19.
2. Install Red Hat Enterprise Linux on the machines and ensure to meet the
software prerequisites and to apply all the configurations described in
Manage-from requirements on page 21.
When installing the Red Hat Enterprise Linux operating system for the IBM
Cloud Orchestrator servers, the Basic Server package group is sufficient,
because the IBM Cloud Orchestrator servers deploy script installs the required
packages from the corresponding YUM repository or Red Hat ISO files.
3. Ensure that the hardware clock is configured as UTC. The final line in the
/etc/adjtime file should be the text UTC, as shown in the following example:
619.737272 1411131873 0.000000
1411131873
UTC

4. If you are using virtual machines, ensure that all the clocks are synchronized
with the host clock.
5. Make sure that SELINUX is disabled on Central Server 2. To disable SELINUX, edit
the /etc/selinux/config file and set the parameter SELINUX=disabled. Reboot
the node.
6. Remove the following packages on the Deployment Server and on each IBM
Cloud Orchestrator server, if installed:
facter
hiera
mcollective
mcollective-common
subversion-ruby
libselinux-ruby
ruby-augeas
ruby-rgen
ruby-shadow
rubygem-json
rubygem-stomp
rubygems

To remove the packages, run the following commands:

yum -y remove

facter, hiera, mcollective, mcollective-common, subversion-ruby,

libselinux-ruby, ruby-augeas, ruby-rgen, ruby-shadow, rubygem-json,
rubygem-stomp, rubygems

7. Create a backup of the Deployment Server and of each IBM Cloud Orchestrator
server. For example, create a snapshot of each virtual server.

Downloading the required image files

Before you install or upgrade, download the required image files.

Before you begin

Prepare the Deployment Server (that is, the physical or virtual server where you
install the Deployment Service), as described in Preparing the IBM Cloud
Orchestrator servers on page 31.

About this task

You copy the required image files to a temporary directory, such as
/opt/ico_install, on the Deployment Server.

32

IBM Cloud Orchestrator 2.4.0.2: User's Guide

If you are upgrading, copy the image files to a different temporary location, such
as /opt/ico_install_2402. Do not overwrite the original installation files.
In this procedure, the example temporary directory is /opt/ico_install. Replace
/opt/ico_install with the appropriate value for your installation or upgrade.

Procedure
1. Download the required IBM Cloud Orchestrator image files:
v If you want to install or upgrade to IBM Cloud Orchestrator V2.4.0.2 or IBM
Cloud Orchestrator Enterprise Edition V2.4.0.2, download the following files
from the IBM Fix Central site:
2.4.0-CSI-ICO-FP0002
2.4.0-CSI-ICO-FP0002.README

[Upgrade only] The following additional fix package is required if upgrading

to IBM Cloud Orchestrator V2.4.0.2:
2.4.0-CSI-ICO-FP0002-WORKLOAD-DEPLOYER-efixes

v If you want to install or upgrade to IBM Cloud Orchestrator V2.4, download

the following images from the IBM Passport Advantage site:
ICO_V240_1of4.tar
ICO_V240_2of4.tar
ICO_V240_3of4.tar
ICO_V240_4of4.tar

v If you want to install or upgrade to IBM Cloud Orchestrator Enterprise

Edition V2.4, download the following images from the IBM Passport
Advantage site:
ICO_Ent_V240_1of4.tar
ICO_V240_2of4.tar
ICO_V240_3of4.tar
ICO_V240_4of4.tar

2. Copy the IBM Cloud Orchestrator image files to the Deployment Server and
extract the contents. For example, to extract the contents of the image files into
the /opt/ico_install directory, run the following command for each image file:
tar -xf image_file.tar -C /opt/ico_install

3. Download the following Business Process Manager packages and copy them to
the/opt/ico_install/data/orchestrator-chef-repo/packages/bpm_binaries/
directory:
BPM_Std_V85_Linux_x86_1_of_3.tar.gz
BPM_Std_V85_Linux_x86_2_of_3.tar.gz
BPM_Std_V85_Linux_x86_3_of_3.tar.gz

4. Download the following IBM HTTP Server packages and copy them to the
/opt/ico_install/data/orchestrator-chef-repo/packages/ihs_binaries/
directory:
WAS_V85_SUPPL_3_OF_3.zip
WAS_V85_SUPPL_2_OF_3.zip
WAS_V85_SUPPL_1_OF_3.zip

5. If you want to install or upgrade IBM Cloud Orchestrator with high availability
capabilities, download the following additional packages.
a. Download the following System Automation for Multiplatforms packages
and copy them to the /opt/ico_install/data/orchestrator-chef-repo/
packages/samp/ directory:
SA_MP_4.1_Linux.tar
4.1.0-TIV-SAMP-Linux-FP0001.tar

Chapter 2. Installing

33

b. Download the following System Automation Application Manager package

and copy it to the /opt/ico_install/data/orchestrator-chef-repo/
packages/saam/ directory:
SA_AM_4.1_LinSysX.tar

c. Download the following Jazz for Service Management package and copy it
to the /opt/ico_install/data/orchestrator-chef-repo/packages/jazzsm
directory:
JAZZ_FOR_SM_1.1.0.2_FOR_LINUX_ML.zip

d. Download the following WebSphere Application Server for Jazz for Service
Management package and copy it to the /opt/ico_install/data/
orchestrator-chef-repo/packages/was directory:
WAS_V8.5.0.1_FOR_JAZZSM_LINUX_ML.zip

e. Download the following IBM DB2 package and copy it to the

/opt/ico_install/data/orchestrator-chef-repo/packages/db2 directory:
IBM_DB2_10.1_-_Limited_Use_for_Li.tar.gz

6. If you are using a Red Hat Enterprise Linux ISO file instead of using Red Hat
Subscription Management or yum as a package repository, copy the ISO file to
the /opt directory on the Deployment Server. For more information about the
Red Hat Enterprise Linux version required, see Software prerequisites on
page 21.
7. If you want to install or upgrade the additional components for IBM Cloud
Orchestrator Enterprise Edition, see the Download Document for a list of the
images to be downloaded for the following products:
v IBM SmartCloud Cost Management
v IBM Tivoli Monitoring
v IBM Tivoli Monitoring for Virtual Environments
v Jazz for Service Management
For information about installing IBM Cloud Orchestrator Enterprise Edition, see
Installing IBM Cloud Orchestrator Enterprise Edition on page 71.

Installing the Deployment Service

The Deployment Service is the bootstrap of the IBM Cloud Orchestrator installer. It
installs all the services that are required to deploy or maintain an IBM Cloud
Orchestrator environment.

Before you begin

Before you install the Deployment Service, prepare the Deployment Server as
described in Preparing the IBM Cloud Orchestrator servers on page 31. When
the operating system is installed and configured, copy the required installation
packages (such as IBM Cloud Orchestrator, Business Process Manager, and IBM
HTTP Server) to the Deployment Server, as described in Downloading the
required image files on page 32.
You do not have to be a root user to install the Deployment Service. A nonroot
user can install if the user has sudo access privileges. To configure a user with sudo
access privileges, add the following line to the /etc/sudoers file:
<user> ALL=(ALL)NOPASSWD:ALL

34

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

To install the Deployment Service, complete the following procedure. You must
have already unpacked the IBM Cloud Orchestrator installation package in a
temporary directory. In this procedure, the example temporary directory is
/opt/ico_install. Replace /opt/ico_install with the appropriate value for your
installation.

Procedure
1. Log on to the Deployment Server.
2. Edit the /opt/ico_install/installer/deployment-service.cfg configuration
file to specify the appropriate value for the following parameters:
iso_location
Specifies the location of the ISO image file for the Red Hat Enterprise
Linux 6 (x86_64) installation DVD. This parameter is optional. If the
Deployment Server is registered with Red Hat Subscription
Management or Red Hat Network, or is configured to use an available
Yum repository, the location can be blank. If you are using a
customized Yum repository, ensure that the Yum repository is at the
same version level as the operating system.
managment_network_device
Specifies the network interface that is used to access the other servers
in the IBM Cloud Orchestrator management stack (that is, Central
Servers, Region Servers, Neutron Server, Compute Nodes). The default
value is eth0.
package_checking
Specifies whether the installer should verify that the required packages
for the High-Availability Distributed topology are in the correct location
on the Deployment Server. If this parameter is set to yes and any
required package is not found, the installation stops with an error. If
this parameter is set to no, the installer does not check the packages.
For the High-Availability Distributed topology, this parameter should
be set to yes. For the Demo topology or Distributed topology, this
parameter must be set to no.
Note: This parameter applies to the High-Availability Distributed
topology only. For the Demo topology or Distributed topology, you
must manually check that the required Business Process Manager and
IBM HTTP Server packages are in the correct location on the
Deployment Server. If any required package is not found, the
installation stops with an error. For more information about where the
packages should be located on the Deployment Server, see
Downloading the required image files on page 32.
ntp_servers
Specifies the IP address or fully qualified domain name of the NTP
server. If no value is specified, the installer uses the Deployment Server
as the NTP server for any deployed environments. To specify multiple
servers, use a comma separator. Ensure that at least one of the specified
servers is available.
3. If you are installing the High-Availability Distributed topology, you must
enable the load balancer Yum repository. To specify that the load-balancer
repository for a specific system should be managed by Red Hat Network,
complete the following steps:
Chapter 2. Installing

35

a.
b.
c.
d.

In the Red Hat Network interface, click the Systems tab.

Select the system.
Click Software > Software Channels.
In the Software Channel Subscriptions list, ensure that the RHEL Server
Load Balancer channel option is selected.

For more information about the load balancer repository, see the Red Hat
documentation.
4. Ensure that the /etc/yum.repos.d/ds.repo file does not exist on the
Deployment Server. If no operating system Yum repository is already
configured on the Deployment Server, the Deployment Service provides its own
internal Yum repository.
5. Ensure that the host name of the Deployment Server is specified correctly in
the /etc/hosts file or in the corporate DNS server. For more information about
how to verify the host name configuration, see Software prerequisites on
page 21.
6. Install the Deployment Service by running the following command:
cd /opt/ico_install/installer; sudo ./deploy_deployment_service.sh

7. If the installation does not complete successfully, review the following log files:
v /var/log/cloud-deployer/deployer_bootstrap.log
v /var/log/cloud-deployer/deploy.log
Take the appropriate action as indicated in the log files, and repeat step 6.

Results
The Deployment Service is installed. In accordance with security best practices,
remember to change the default passwords on the Deployment Server, as described
in Changing the Deployment Service passwords on page 125.

Understanding deployment templates

The deployment templates define the IBM Cloud Orchestrator topology.
Depending on the installation scenario chosen, described in Deployment
topologies on page 16, you can use the following types of templates:
v Deployment templates for demo topology on page 211
v Deployment templates for distributed topology on page 211
v Deployment templates for high-availability distributed topology on page 213
To list all of the available deployment templates, run the ds template-list
command on the Deployment Server. For each template, you can see a short
description of the associated topology.
source /root/keystonerc; ds template-list

Example output:
+--------------------------------------+-----------------------| id
| name
+--------------------------------------+-----------------------...
| b779f01e-95d6-4ca6-a9ec-a37753f66a2b | sco-allinone-kvm
...
+----------------------------------------------------------------------+-------| description
| status
+----------------------------------------------------------------------+--------

36

IBM Cloud Orchestrator 2.4.0.2: User's Guide

...
| SCO Core + additional KVM compute node deployment (Existing machines)| ACTIVE
...
+----------------------------+----------------------------+
| created_at
| updated_at
|
+----------------------------+----------------------------+
...
| 2014-03-27T06:04:01.533856 | 2014-03-27T06:58:40.911237 |
...

For more details about the required resources for the template, run the ds
template-resources-list command.
Example:
source /root/keystonerc; ds template-resources-list b779f01e-95d6-4ca6-a9ec-a37753f66a2b

Example output:
+---------+------------------+-----------------------------+-----------+
| name
| type
| run_list
| run_order |
+---------+------------------+-----------------------------+-----------+
| control | Existing Machine | role[sco-allinone-kvm-mgm] | 1
|
| compute | Existing Machine | role[kvm-compute]
| 2
|
| iwd
| Existing Machine | role[iwd]
| 3
|
+---------+------------------+-----------------------------+-----------+

To display a complete list of Deployment Service commands, run the ds --help

command.
source /root/keystonerc; ds --help

Customizing deployment parameters

The Deployment Service provides default values for most of the parameters
needed to deploy IBM Cloud Orchestrator. If the default values are not able to
meet your environment, you can use the CLI or wizard to override these values.
To list the deployment template parameters, run the following command:
ds template-parameters-list <template_uuid>

where <template_uuid> is the ID of the template that you can get by running the
ds template-list command.
For a list of the deployment parameters, see Deployment parameters on page
213.
If you plan to use Neutron networks, consider that:
v The MGMNetInterface parameter represents an interface that must connect to a
public and routable network.
v The DATANetInterface parameter represents an interface that must connect to a
network dedicated for VXLAN data.
v The EXTNetInterface parameter represents an interface that is used to connect to
a network for external access.
You can have the following three Neutron network topologies:

Chapter 2. Installing

37

Figure 1. Neutron network topology 1

For this topology, MGMNetInterface = eth0, DATANetInterface = eth0 and

EXTNetInterface = eth0.

Figure 2. Neutron network topology 2

For this topology, MGMNetInterface = eth0, DATANetInterface = eth1 and

EXTNetInterface = eth0.

Figure 3. Neutron network topology 3

For this topology, MGMNetInterface = eth0, DATANetInterface = eth1 and

EXTNetInterface = eth2.

38

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Neutron network topology 1 is used for simple deployment, Neutron network

topology 2 is used for production environment, and Neutron network topology 3 is
used only in a complex environment.
Note:
v The NIC name must be the same for all nodes if they are all in the same
network.
v The Compute Nodes can be KVM hypervisors, Hyper-V servers, or ESXi servers.

Deploying an IBM Cloud Orchestrator environment

Deploy an IBM Cloud Orchestrator environment according to your business needs.
To deploy IBM Cloud Orchestrator, perform the following steps:
1.
2.
3.
4.
5.

Register the resources, virtual or physical machines, in the Deployment Service.

Select the IBM Cloud Orchestrator to deploy.
Provide the deployment parameters.
Run the deployment job.
Extend the existing IBM Cloud Orchestrator environment.

You can run the previous procedure by using either a console-based wizard or the
command line interface.
Note: If you use a password whose set of allowed characters is a-zA-Z0-9!()-.?[]
the installation of the Central Server completes successfully.
Before starting the IBM Cloud Orchestrator deployment, it is important to
understand the concepts and artifacts that are used by the Deployment Service:
Node

The resource that is used to deploy or configure IBM Cloud Orchestrator.

There two type of nodes, one is general node that is used to represent a
virtual machine or physical machine, the other one represents the database,
in case you want to use an external DB2.

Template
The deployment template that is used to define different topologies of IBM
Cloud Orchestrator.
Parameter
The parameter inside the template. It is used to customize the deployment
of IBM Cloud Orchestrator, for example to define the network type or the
passwords.
Deployment job
used to define the deployment of the IBM Cloud Orchestrator
environment. It can be a hierarchy if two jobs are related, for example,
Central Server and Region Server jobs (the Region Server jobs depend on
the Central Server job).
Note: Non-English characters are not supported in the Node, Template, Parameter
and Deployment job name. Make sure to use English names for those resources.

Chapter 2. Installing

39

Configuring an external database

If you want to use an external database in your IBM Cloud Orchestrator
environment, you must configure it by following this procedure.
After the Deployment Service has been installed, you can deploy IBM Cloud
Orchestrator to make use of your own external database. IBM Cloud Orchestrator
does not create its own database server instance but leverages the external
database server. The external database must be DB2 version 10.5.0.2 or higher.
Note: For the high-availability topology, an external database is a mandatory
prerequisite.
IBM Cloud Orchestrator supports the following installation types:
v Shared database having separate instances:
IBM Cloud Orchestrator is being installed using a separate instance.
v Shared instance:
IBM Cloud Orchestrator is being installed to a shared instance having other non
IBM Cloud Orchestrator database schemas.
Due to the update and maintenance scenarios, it is strongly recommend to use a
separate database instance for IBM Cloud Orchestrator. It might happen that
during an installation scenario the database instance will be restarted
automatically. For the database instance authentication method, server encryption
should be switched on if not already done. This can be done by running the
following commands using the database instance owner:
db2 update dbm cfg using authentication server_encrypt
db2stop force
db2start

Note: The above is valid also for High Availability.

To configure an external database, perform the following steps:
1. Prepare the databases for IBM Cloud Orchestrator.
2. Create database nodes for IBM Cloud Orchestrator on page 42.
3. Run the deployment job on page 44

Prepare the databases for IBM Cloud Orchestrator

Perform the following steps:
1. From the installer package, copy the data/orchestrator-chef-repo/packages/
workload_deployer/archive.zip and /install-package-directory/installer/
create_dbs.sh files to a directory of your choice on the database machine.
2. Log in to the database machine as root and give executable permission to the
script create_dbs.sh.
3. Set the following environment variables before executing create_dbs.sh:
export DB2_INSTANCE_USER=<your db2 instance user name, for example db2inst1>
export DB2_INSTANCE_PWD=<your db2 instance password>
export USER_DEFAULT_PWD=<default password of database users>

4. Run ./create_dbs.sh all

This creates databases for the Central Server and a single Region Server with
default values.

40

IBM Cloud Orchestrator 2.4.0.2: User's Guide

If you just want to create databases for the Central Server on this machine, run
./create_dbs.sh central
If you just want to create databases for a single Region Server on this machine, run
./create_dbs.sh region
If you just want to create databases for multiple Region Servers on this machine
assumed you want to deploy three regions, run ./create_dbs.sh region=1,2,3
If you want to add a database for a new Region Server on this machine, for
example, a fourth Region Server, run ./create_dbs.sh region=4
The script uses the default environment variable to create the database, user and
schema against the specific DB2 instance on the database server. The default
values of the configuration are defined in the script and can be overridden by
exporting the system environment variables before running the create_dbs.sh
script. If you create a database for multiple regions, it uses the same database
with different user/schema in the database server. For example, the create_dbs.sh
region command creates nova user in system and database, the create_dbs.sh
region=1,2,3 command create nova1, nova2, nova3 in the system and database for
each region.
Note that the script assumes that the database and user/schema do not exist before
you run the script. You must check the DB2 server to make sure that there is not
conflict.
The following default environment variables are used in the create_dbs.sh script:
OS_DB_NAME=<OpenStack DB Name, default=OPENSTAC>
DB2_INSTANCE_PORT=<DB2 instance port, default=50000>
OS_NOVA_DB_NAME=<OpenStack Nova DB User, default=OPENSTAC>
OS_NOVA_DB_USER=<OpenStack Nova DB User, default=nova>
OS_NOVA_DB_PWD=<OpenStack Nova DB Password>
OS_CINDER_DB_NAME=<OpenStack Cinder DB Name, default=OPENSTAC>
OS_CINDER_DB_USER=<OpenStack Cinder DB User, default=cinder>
OS_CINDER_DB_PWD=<OpenStack Cinder DB Password>
OS_HEAT_DB_NAME=<OpenStack Heat DB Name, default=OPENSTAC>
OS_HEAT_DB_USER=<OpenStack Heat DB User, default=heat>
OS_HEAT_DB_PWD=<OpenStack Heat DB Password>
OS_DASH_DB_NAME=<OpenStack Dashboard DB Name, default=OPENSTAC>
OS_DASH_DB_USER=<OpenStack Dashboard DB User, default=dash>
OS_DASH_DB_PWD=<OpenStack Dashboard DB Password>
OS_KEYSTONE_DB_NAME=<OpenStack Keystone DB Name, default=OPENSTAC>
OS_KEYSTONE_DB_USER=<OpenStack Keystone DB User, default=keystone>
OS_KEYSTONE_DB_PWD=<OpenStack Keystone DB Password
OS_NEUTRON_DB_NAME=<OpenStack Neutron DB Name, default=OPENSTAC>
OS_NEUTRON_DB_USER=<OpenStack Neutron DB User, default=neutron>
OS_NEUTRON_DB_PWD=<OpenStack Neutron DB Password>
OS_CEIL_DB_NAME=<OpenStack Ceilometer DB Name, default=OPENSTAC>
OS_CEIL_DB_USER=<OpenStack Ceilometer DB User, default=ceil>
OS_CEIL_DB_PWD=<OpenStack Ceilometer DB Password>
OS_CEIL_DB_NOSQLPORT=<Mongo DB Port, default=27017>
OS_GLANCE_DB_NAME=<OpenStack Glance DB Name, default=OPENSTAC>
OS_GLANCE_DB_USER=<OpenStack Glance DB User, default=glance>
OS_GLANCE_DB_PWD=<OpenStack Glance DB Password>
BPM_DB_NAME=<BPM DB Name, default=BPMDB>
BPM_DB_USER=<BPM DB User, default=bpmuser>
BPM_DB_PWD=<BPM DB Password>
CMN_DB_NAME=<CMN DB Name, default=CMNDB>
CMN_DB_USER=<CMN DB User, default=bpmuser>

Chapter 2. Installing

41

CMN_DB_PWD=<CMN DB Password>
PDW_DB_NAME=<PDW DB Name, default=PDWDB>
PDW_DB_USER=<PDW DB User, default=bpmuser>
PDW_DB_PWD=<PDW DB Password>

Note:
v Database name length must be no more than eight characters, for example,
OPENSTAC and not OPENSTACK.
v For Business Process Manager databases (BPMDB, CMNDB and PDWDB), if you
use the same user name for different databases, make sure that you use the
same password too. Do not use different passwords for the same user.
v Make sure to set the USER_DEFAULT_PWD or the default password is passw0rd.
v Make sure to set correctly the firewall to allow the DB2 communication. The
default port numbers are 50000 and 27017.
v If you need to restart the DB, after restarting, you need to restart NoSQL by
following the procedure described in Restarting NoSQL on page 235.
The following is an example of the output of create_dbs.sh:
{ Address: <HOSTNAME>, Port: 50000, Name: OPENSTAC, User: nova, Password: <PASSWORD>, Fqdn: <HOSTNAME>}
{ Address: <HOSTNAME>, Port: 50000, Name: OPENSTAC, User: dash, Password: <PASSWORD>, Fqdn: <HOSTNAME>}

Normally external database machines are not for IBM Cloud Orchestrator only, it
may have databases used by other services. It is not appropriate to restart the DB2
service there:
1. Log on to the external database server with db2 instance user.
2. Update dbm cfg using the command:
db2 update dbm cfg using authentication server_encrypt

3. Restart the database service using:

db2stop force
db2start

Note: If the database cannot be stopped, stop the applications which are
locking the related database.

Create database nodes for IBM Cloud Orchestrator

Use the ds template-list command to identify the template that best fits your
need. The names of the templates for external database ends with -extdb, for
example, sco-allinone-extdb and sco-central-region-extdb. You can perform the
following procedure or use the Deployment Service wizard as described in
Deploying the Central Servers on page 44. If you want to use the command-line
interface, perform the following steps:
1. Log on to the Deployment Server and run the following command:
source keystonerc

2. Identify the nodes to be registered by looking at the resource names of type

Existing Database in the output of the ds template-resources-list command.
For example:
ds template-resources-list sco-allinone-extdb
+------------------+-------------------+--------------------------+-----------+
| name
| type
| run_list
| run_order |
+------------------+-------------------+--------------------------+-----------+
| control
| Existing Machine | role[sco-allinone-extdb] | 1
|
| compute
| Existing Machine | role[kvm-compute]
| 2
|
| bpm_db
| Existing Database |
|
|

42

IBM Cloud Orchestrator 2.4.0.2: User's Guide

| cmn_db
| Existing Database |
|
|
| compute_db
| Existing Database |
|
|
| dashboard_db
| Existing Database |
|
|
| image_db
| Existing Database |
|
|
| keystone_db
| Existing Database |
|
|
| metering_db
| Existing Database |
|
|
| network_db
| Existing Database |
|
|
| orchestration_db | Existing Database |
|
|
| pdw_db
| Existing Database |
|
|
| volume_db
| Existing Database |
|
|
+------------------+-------------------+--------------------------+-----------+

3. List the node type by running the following command:

ds node-type-list
+--------------------+
| type
|
+--------------------+
| IBM::SCO::Node
|
| IBM::SCO::Database |
+--------------------+

4. Show the node properties by running the following command:

ds node-type-show -p IBM::SCO::Database
+------------+---------+--------+----------------+------------------------------------+
| Properties | Default | Type
| Update
| Description
|
+------------+---------+--------+----------------+------------------------------------+
| Name
|
| string | True
| The database nam
|
| NoSqlPort | 27017
| number | True
| The database no SQL port
|
| Fqdn
|
| string | True
| The FQDN of the database machine |
| User
|
| string | True
| The database schema user
|
| Address
|
| string | True
| The Address of the database machin |
| Password
|
| string | True
| The database password
|
| Port
| 50000
| number | True
| The database port
|
+------------+---------+--------+----------------+------------------------------------+

5. Create database nodes for all the existing database resources by running the
following commands (each command on one line):
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: cinder, Password: admin, Name: openstac}
volume_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: nova, Password: admin, Name: openstac}
compute_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: dash, Password: admin, Name: openstac}
dashboard_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: glance, Password: admin, Name: openstac}
image_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: keystone, Password: admin, Name: openstac}
keystone_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: ceil, Password: admin, Name: openstac}
metering_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: neutron, Password: admin, Name: openstac}
network_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: heat, Password: admin, Name: openstac}
orchestration_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: bpmuser, Password: password, Name: CMNDB}
cmn_db

Chapter 2. Installing

43

ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: bpmuser, Password: password, Name: BPMDB}
bpm_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: bpmuser, Password: password, Name: PDWDB}
pdw_db

You can verify that the nodes were successfully created by running the ds
node-list command.
Because both the KVM Region and the VMware Region will use compute_db,
image_db, network_db, orchestration_db, and volume_db, so if you decide to install
both the KVM and VMware Region, you must create these database twice with
different names.
The following is an example for compute_db (each command on one line)::
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: nova, Password: passw0rd, Name: openstac}
kvm_compute_db
ds node-create -t IBM::SCO::Database
-p {Address: 192.0.2.147, User: nova, Password: passw0rd, Name: openstac}
vmware_compute_db

Run the deployment job

The following section on how to create and run a deployment job is just an
example. If you are performing the database setup for a high availability
environment, follow the instructions on Installing the Central Servers on page
55.
Before running a deployment job, create it by running the following command (on
one line), for example:
ds job-create -N "dashboard_db=dashboard_db;compute_db=compute_db;cmn_db=cmn_db;
bpm_db=bpm_db;control=control;metering_db=metering_db;
network_db=network_db;orchestration_db=orchestration_db;
compute=compute;image_db=image_db;pdw_db=pdw_db;
keystone_db=keystone_db"
-t sco-allinone-extdb sco-allinone-extdb

Run the job by using the ds job-execute command.

Deploying the Central Servers

Use the Deployment Service wizard to deploy the IBM Cloud Orchestrator Central
Servers.

About this task

To use the Deployment Service wizard, the terminal window must be at least 35
lines and 130 columns.

Procedure
1. [Nonroot user only:] If you want to deploy the IBM Cloud Orchestrator Central
Servers as a nonroot user, create an openrc file in your home directory, and
insert the following content:

44

IBM Cloud Orchestrator 2.4.0.2: User's Guide

export
export
export
export
export

OS_USERNAME=admin
OS_PASSWORD=$(openstack-obfuscate -u encrypted_admin_password)
OS_TENANT_NAME=admin
OS_AUTH_URL=http://fqdn_or_ip_address_of_deployment_service_node:5000/v2.0
OS_REGION_NAME=Deployment

2. To run any ds command, you must first source the openrc file:
source ~/openrc

3. Start the Deployment Service wizard:

ds wizard [-f]

Specify the -f parameter if you want to generate a file that records the
commands that are used by the wizard.
4. Choose the following option to deploy the IBM Cloud Orchestrator Central
Servers:
[0] New IBM Cloud Orchestrator deployment.
- Start a new IBM Cloud Orchestrator deployment.

When prompted, enter the required information. For information about the
deployment parameters, see Deployment parameters on page 213.
5. [Optional:] To review the deployment progress, complete the following steps:
a. Choose the following wizard option:
[4] Deployment job(s) status.
- Display deployment job(s) status.

b. Review the list of jobs and identify your deployment job.

c. [Optional:] To display additional information about the job, type the menu
option number for that job, and press Enter.
6. If you do not create a job correctly and you want to delete the job, you must
use the CLI ds job-delete command. You cannot delete a job by using the
wizard.
7. When the status of the job is FINISHED, the deployment is complete.

Results
The IBM Cloud Orchestrator Central Servers are installed.

Deploying a Region Server

After the initial deployment, you can add a Region Server to your environment.
You can add any of the following Region Servers:
v Hyper-V region with Neutron network
v KVM region with Nova network
v KVM region with Neutron network
v PowerVC region with Neutron network
v VMware region with Nova network
v VMware region with Neutron network
v z/VM region with Neutron network
For more information about Nova networks, see Managing Nova networks on
page 88. For more information about Neutron networks, see Managing Neutron
networks on page 93.
Before you begin
Chapter 2. Installing

45

Verify that the Deployment Server and the Central Servers are ready in your
environment. For more information about installing the Deployment Server and
the Central Servers, see Installing the Deployment Service on page 34 and
Deploying the Central Servers on page 44.
VMware only: Do not install more than one IBM Cloud Orchestrator instance on
the same vCenter environment if the instances have access to the same resources.
Each IBM Cloud Orchestrator instance must use a different userid to access the
vCenter. The intersection between the resources that are seen by these users (for
example, clusters, datastore) must be empty.
PowerVC only: Ensure that the PowerVC server has been installed.
Note: Using a PowerVC server that has been configured for both Shared Storage
Pools and SAN-fabric managed Storage is not recommended. If possible, you
should use two PowerVC servers, each configured for using a single Storage Type,
and two PowerVC Region Servers (including two PowerVC Neutron Servers) to
manage them.
Note: PowerVC must be at version 1.2.1.2 and you must also apply the interim fix
shipped with IBM Cloud Orchestrator. For more information, see Applying
interim fix 1 to PowerVC 1.2.1.2 on page 50.
z/VM only: You must enable the xCAT version that is provided with z/VM 6.3. To
enable xCAT for z/VM 6.3, follow chapters 1-4 in the Enabling z/VM for OpenStack
(Support for OpenStack Icehouse Release) guide, at http://www.vm.ibm.com/
sysman/openstk.html.
Procedure
To deploy a Region Server, use the Deployment Service wizard as described in
Deploying the Central Servers on page 44 and choose the following option:
[1] Modify IBM Cloud Orchestrator deployment.
- Modify an IBM Cloud Orchestrator deployment, add region server or KVM compute node.

Use this option to deploy a Region Server of any hypervisor type: Hyper-V, KVM,
PowerVC, VMware, or z/VM.
If you deploy a KVM Region Server, you must choose this option again to create a
KVM compute node. For multiple KVM compute nodes, you must choose this
option multiple times: once for each KVM compute node.
You cannot use the wizard to deploy a Hyper-V compute node. Instead, you must
use the procedure documented in Installing a Hyper-V compute node on page
47.
Follow the interactive procedure by entering the required information. For
information about the deployment parameters, see Deployment parameters on
page 213.
Note: If you do not create a job correctly and you want to delete the job, you must
use the CLI ds job-delete command. You cannot delete a job by using the wizard.
For information about how to install a Region Server by using the command-line
interface, see Deploying a Region Server (CLI method) on page 201.

46

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Configuring a Region Server

After you install a Region Server, some hypervisor-specific configuration tasks
might be necessary, depending on the hypervisor used.
Installing a Hyper-V compute node:
This topic describes how to install Hyper-V services by using the official IBM
Cloud Manager with the OpenStack 4.1 documentation.
Before you begin
Before you create a Hyper-V compute node, you must first create a Hyper-V
server.
Also, check the network prerequisites for the Neutron Server:
1. Ensure that the iproute packages are installed as described in Software
prerequisites on page 21.
2. Ensure that IP forwarding is enabled on the Neutron Server. To check whether
IP forwarding is enabled, run the following command:
cat /proc/sys/net/ipv4/ip_forward

The command should return the value 1. If not, you can enable IP forwarding
in the /etc/sysctl.conf file. To activate the setting without rebooting, run the
sysctl -p command.
About this task
To create a Hyper-V compute node, you install the Hyper-V compute services on a
Hyper-V server. Hyper-V Compute Nodes cannot be installed by using the
Deployment Service wizard, and must be installed manually as described in this
topic.
Procedure
1. From the location where you extracted the IBM Cloud Orchestrator package,
there are two files:
/data/openstack/packages/driver/IBM Cloud Manager with OpenStack Hyper-V Agent.msi
/data/openstack/packages/ntp/ntp-4.2.6p5-ibm-win32-setup.exe

You must make them available to your Hyper-V server(s).

2. Install ntp-4.2.6p5-ibm-win32-setup.exe to sync time.
3. Configure the time correctly, ensure that there is no time lag bigger than 15
minutes.
4. Create a virtual Switch in the Hyper-V manager if not already done. The
installer allows to create a virtual switch during installation but there are
circumstances when this does not work reliably. So it is advised to create the
virtual switch in advance using the tools provided by Microsoft.
5. Install the IBM Cloud Manager with OpenStack installer, using these values:
Table 6.
Parameter

Value

glance api server

<Region Server_FQDN> (If it is not possible to

use or configure DNS, IP addresses can be
used)

Chapter 2. Installing

47

Table 6. (continued)
Parameter

Value

qpid server

<Region Server_FQDN> (If it is not possible to

use or configure DNS, IP addresses can be
used)

qpid port

5672

qpid username

guest

qpid password

<qpid password>

neutron URL

http://<Region Server_FQDN>:9696

username

neutron

password

<password in neutron>

tenant name

service

region name

<region name>

authentication URL

http://<Central Server 2_FQDN>:5000/v2.0

Use existing Virtual Switch

<SwitchName> as created in Step 4

6. Change qpid_protocol=tcp in: c:\Program Files (x86)\IBM\Cloud Manager

with OpenStack\Hyper-V Agent\etc\nova\nova.conf.
7. Change qpid_protocol=tcp in c:\Program Files (x86)\IBM\Cloud Manager
with OpenStack\Hyper-V Agent\etc\neutron\neutron.conf.
8. Change physical_network_vswitch_mappings=*:<NAME_OF_VSWITCH> in
c:\Program Files (x86)\IBM\Cloud Manager with OpenStack\Hyper-V
Agent\etc\neutron\hyperv_neutron_agent.ini. The name of the vswitch is the
one you created in Step 4.
9. Verify the network settings in c:\Program Files (x86)\IBM\Cloud Manager
with OpenStack\Hyper-V Agent\etc\neutron\hyperv_neutron_agent.ini. In
particular, the VLAN ranges, for example:
network_vlan_ranges=default:100:3999

10. When planning to run with multiple Hyper-V compute nodes, make sure that
all of them are enabled for live migration (otherwise the virtual machine
resize operations will fail). For details see http://docs.openstack.org/
icehouse/config-reference/content/hyper-v-virtualization-platform.html.
11. For Hyper-V-Server only you need to Install an ISO tool (for example, cygwin
genisomiage) according to: http://dev15alt2.raleigh.ibm.com:9090/kc/
SST55W_4.1.0/liaca/
liaca_enabling_hyperv_2012_systems_for_iso_generation.html in c:\Program
Files (x86)\IBM\Cloud Manager with OpenStack\Hyper-V
Agent\etc\nova\nova.conf update the location of the iso image tool you chose,
for example cygwin genisoimage:
mkisofs_cmd=c:\cygwin64\bin\genisoimage.exe

12. Set the config_drive options:

In c:\Program Files (x86)\IBM\Cloud Manager with OpenStack\Hyper-V
Agent\etc\nova\nova.conf set the following two parameters:
force_config_drive=always
config_drive_inject_password=True

13. For multiple region, you must specify the following parameter in c:\Program
Files (x86)\IBM\Cloud Manager with OpenStack\Hyper-V
Agent\etc\nova\nova.conf:
cinder_endpoint_template=http://<RegionServer_FQDN>:8776/v1/%(project_id)s

48

IBM Cloud Orchestrator 2.4.0.2: User's Guide

14. Restart IBM Cloud Manager with OpenStack Compute Service and IBM Cloud
Manager with OpenStack Network Service.
Here are the commands to start and stop the Hyper-V services:
net
net
net
net

stop "IBM Cloud Manager with OpenStack Compute Service"

stop "IBM Cloud Manager with OpenStack Network Service"
start "IBM Cloud Manager with OpenStack Compute Service"
start "IBM Cloud Manager with OpenStack Network Service"

15. Ensure that the VLAN network range is correct for your environment.
On the Hyper-V Compute Node, edit the C:\Program Files (x86)\IBM\Cloud
Manager with OpenStack\Hyper-V Agent\etc\neutron\
hyperv_neutron_agent.ini configuration file, and verify that the specified
network_vlan_ranges value is suitable for your environment, as shown in the
following example:
network_vlan_ranges=default:100:3999

Installing a KVM compute node:

Before you can use a KVM Region Server, you must install at least one KVM
compute node.
About this task
You can use the Deployment Service wizard to create a KVM compute node. The
terminal window must be at least 35 lines and 130 columns.
Procedure
1. [Nonroot user only:] If you want to install the KVM compute node as a nonroot
user, create an openrc file in your home directory, and insert the following
content:
export
export
export
export
export

OS_USERNAME=admin
OS_PASSWORD=$(openstack-obfuscate -u encrypted_admin_password)
OS_TENANT_NAME=admin
OS_AUTH_URL=http://fqdn_or_ip_address_of_deployment_service_node:5000/v2.0
OS_REGION_NAME=Deployment

2. To run any ds command, you must first source the openrc file:
source ~/openrc

3. Start the Deployment Service wizard:

ds wizard [-f]

Specify the -f parameter if you want to generate a file that records the
commands that are used by the wizard.
4. Choose the following option to create a KVM compute node:
[1] Modify IBM Cloud Orchestrator deployment.
- Modify an IBM Cloud Orchestrator deployment, add region server or KVM compute node.

When prompted, enter the required information. For information about the
deployment parameters, see Deployment parameters on page 213.
5. To create multiple compute nodes, repeat the previous step as many times as
required. You can create only one compute node at a time.
6. If you do not create a job correctly and you want to delete the job, you must
use the CLI ds command. You cannot delete a job by using the wizard.

Chapter 2. Installing

49

Results
The KVM compute node is created.
Configuring a PowerVC Region Server:
To configure a PowerVC Region Server, you must apply any required fixes, copy
the SSL certificate, and configure storage. You must then restart some services.
Applying interim fix 1 to PowerVC 1.2.1.2:
PowerVC 1.2.1.2 requires an interim fix shipped with IBM Cloud Orchestrator to
be installed in order to function correctly with Workload Deployer.
To do this copy the interim fix from the /utils/powervc/ directory to the server
hosting PowerVC 1.2.1.2 on the PowerVC server, untar the interim fix and then run
the update command:
./update

After the update, it is necessary to restart the PowerVC services on the PowerVC
Region Server if they are already running.
On the PowerVC Region Server run:
service
service
service
service

openstack-glance-powervc restart
openstack-neutron-powervc restart
openstack-nova-powervc restart
openstack-cinder-powervc restart

Post PowerVC Region Server installation tasks:

Complete the following steps after the PowerVC region server has been installed.
Procedure
1. Copy the SSL certificate from the PowerVC server to the PowerVC region
server. The location of the SSL certificate on the PowerVC server is:
/etc/pki/tls/certs/powervc.crt

2. Copy the certificate to the PowerVC region server with the following command
executed on the PowerVC region server:
scp root@<powervc server:/etc/pki/tls/certs/powervc.crt /etc/pki/tls/certs/powervc.crt

3. Verify that all services are running by logging on to Central Server 1 and
running SCOrchestrator.py. For details, refer to Managing services with
SCOrchestrator.py on page 223.
Results
The certificate has been copied to the PowerVC Region Server.
What to do next
Network setup
DHCP is not supported by the PowerVC OpenStack driver. When creating the
network in Horizon for use with PowerVC, ensure that the DHCP box is disabled.
Configure PowerVC with Shared Storage Pools

50

IBM Cloud Orchestrator 2.4.0.2: User's Guide

For the PowerVC Region Server to communicate with PowerVC setup leveraging
Shared Storage Pools it is necessary to manually configure the Storage Connectivity
Groups in /etc/powervc/powervc.conf. In /etc/powervc/powervc.conf on the
Region Server there is a variable named storage_connectivity_group in the
[powervc] section of the configuration file. By default its value is Any host, all
VIOS and this is used for PowerVC systems setup using a SVC. If using Shared
Storage Pools, replace this value with the string specified under Shared Storage
Pool-Backed Groups on the PowerVC User Interface under CONFIGURATION >
Storage Connectivity Groups. If you have more than one Shared Storage
Pool-Backed Groups, or if you want to use a different type of storage, deploy a
PowerVC Region Server per storage connectivity group. Where each PowerVC
Region Server connects to a single Storage Connectivity Group.
Restart the following services:
service
service
service
service
service

openstack-glance-powervc restart
openstack-neutron-powervc restart
openstack-nova-powervc restart
openstack-cinder-powervc restart
openstack-cinder-volume restart

Customizing a z/VM Region Server deployment:

Customize the z/VM Region Server deployment by overriding the default
parameters by using the CLI or the deployment wizard.
For information about using the wizard to deploy, see Deploying the Central
Servers on page 44.
For information about using the CLI to deploy, see Using the command-line
interface to deploy IBM Cloud Orchestrator on page 198.
In the following table, only the parameters related to the z/VM Region Server
deployment are listed. For more information about the deployment parameters, see
Deployment parameters on page 213.
Table 7. z/VM Region Server deployment parameters
Name

Default Value

Description

RegionName

RegionZVM

This is the region name for

OpenStack. It is important only when
you want to deploy a multiple region
environment.
No need to change it for all-in-one
based template.
In a multiple region environment,
region name must be unique.

OSLibvirtType

zvm

The virtualization type.

ComputeDriver

nova.virt.zvm.ZVMDriver

The OpenStack hypervisor driver.

XcatUsername

admin

The user name of xCAT server that is

used to communicate to OpenStack
services.
The xCAT server IP on which this
nova compute node operates.

XcatServer
XcatZhcpNodename

zhcp

The xCAT ZHCP node name in

xCAT.
Chapter 2. Installing

51

Table 7. z/VM Region Server deployment parameters (continued)

Name

Default Value

Description

XcatMaster

xcat

The xCAT master node (the node

name in xCAT definition).

XcatMgtIp

XcatMgtIp

The xCAT management interface IP

address.

XcatMgtMask

255.255.255.192

The xCAT management interface

netmask.

ZvmDiskPool

ROOTP1

The disk pool name from which

xCAT allocates disk for the new
servers.

ZvmDiskPoolType

ECKD

The disk pool type. It can be FBA or

ECKD.

ZvmHost

tivlp57

The node name of the z/VM

hypervisor.

VswitchMappings

xcatvsw1:6443;xcatvsw2:6243,5244

The OSA configuration for each

vSwitch. This configuration is
required if the vSwitch needs to
connect outside of z/VM.

DatabagXcatPassword

admin

The password of the xCAT user that

is used to communicate to OpenStack
services.

DatabagZlinuxRootPassword

password

The root password in Linux on

System z to be used for the deployed
virtual machines.

DatabagMnadmin

mnpass

The password of xCAT mnadmin user.

Ml2MechanismDrivers

zvm

The Openstack network ml2

mechanism drivers.

Ml2FlatNetworks

xcatvsw2

The ml2 flat networks.

Installing Workload Deployer in non default directories

This topic describes how to install Workload Deployer in non default directories.

About this task

Workload Deployer needs to use directories like /drouter and /opt/ibm. If you
want to use some custom directories for these two, you must make bind mounts
for them.
Note: Do not use symbolic links. Create links with mount -o bind as described in
the following procedure.

Procedure
1. Create destination directories:
# mkdir /drouter
# mkdir -p /opt/app/workload/sco/drouter /drouter

2. Mount:
# mount -o bind /opt/app/workload/sco/drouter /drouter

52

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This mount is removed after a server shutdown. After being sure that
Workload Deployer works properly, a system administrator can add a
permanent mount to /etc/fstab. For the /opt/ibm directory, the steps are
similar.

Deploying the High-Availability Distributed topology

A high-availability installation requires more hardware than an installation that is
not highly available, and additional process steps are needed.
To deploy the High-Availability Distributed topology, complete the following steps:
1. Install the Deployment Service, as described in Installing the Deployment
Service on page 34.
2. Install an external database.
The High-Availability Distributed topology requires the installation of an
external database. This topology does not support the usage of a shared
database that is installed on the Central Server. This topology also does not
support the usage of a local database for a Region Server. The external database
instance is used to run all databases for the Central Servers and the Region
Servers in the High-Availability Distributed topology, and enables customers to
use established operations procedures from other application databases.
Because the database instance is a key component of IBM Cloud Orchestrator,
you should install IBM DB2 with high-availability features (for example, DB2
HADR or DB2 with shared disk). For more information, see Configuring a
clustered environment using DB2 High Availability Instance Configuration Utility
(db2haicu) in the IBM DB2 documentation (http://www.ibm.com/support/
knowledgecenter/SSEPGG_10.5.0/com.ibm.db2.luw.admin.ha.doc/doc/
t0052800.html).
3. Configure the external database, as described in Configuring an external
database on page 40.
4. Install System Automation Application Manager, as described in Installing
System Automation Application Manager on page 54.
System Automation Application Manager is used to control the starting,
stopping, and automatic restarting of IBM Cloud Orchestrator. System
Automation Application Manager controls all IBM Cloud Orchestrator
application components, simplifies the daily operation tasks, and can
automatically restart failed components. System Automation Application
Manager is installed with its own instance of IBM DB2 installed on the same
node. The separation of the IBM Cloud Orchestrator database from System
Automation Application Manager is needed because System Automation
Application Manager is used to control the IBM Cloud Orchestrator database
instance.
Tip: The System Automation Application Manager installation can be manually
enhanced by configuration as a two-node high-availability cluster. For more
information about this configuration, see Planning for high availability in the
System Automation Application Manager documentation (https://
www.ibm.com/support/knowledgecenter/SSPQ7D_4.1.0/
com.ibm.saam.doc_4.1/toplan_planinstallha.html).
5. Install the active-active Central Servers, as described in Installing the Central
Servers on page 55.
System Automation for Multiplatforms is installed on both the Central Server 2
primary node and the Central Server 2 secondary node. System Automation for
Multiplatforms is a high-availability cluster solution that is used to provide
Chapter 2. Installing

53

failover for components such as haproxy, IBM HTTP Server, and so on. The
automation policy for System Automation for Multiplatforms is fully
automated. The cluster is configured and started after the installation.
6. Install one or more Region Servers, as described in Installing the Region
Server on page 58.
The High-Availability Distributed topology supports the following Region
Server configurations:
v VMware Region with Neutron network
v VMware Region with Nova network
v KVM Region with Neutron network
v KVM Region with Nova network
For all Region Server installations, a policy snippet is created automatically and
is included in the overall System Automation Application Manager policy.
Restriction: For a high-availability installation, only VMware and KVM regions
are supported.
The High-Availability Distributed topology is now installed. Complete the final
configuration steps as described in Configuring high availability on page 119.
For more information about high availability, see Managing high availability on
page 235.

Installing System Automation Application Manager

Use the HA-saam template to install System Automation Application Manager in the
high-availability topology.

Procedure
1. Create a virtual machine with a supported operating system installed. For
information about supported operating systems see Supported hardware and
operating systems.
2. Create a node resource for the virtual machine, and register the resource in the
Deployment Service:
ds node-create -t "IBM::SCO::Node"
-p "{Address: saam_address, Port: 22, User: root, Password: password }" saam

where
IBM::SCO::Node
indicates that the virtual machine is registered as a node resource.
saam_address
is the IP address of the virtual machine.
password
is the root password for the virtual machine.
3. Run the ds template-list command to find the ID of the HA-saam template.
4. Run the ds node-list command to find the ID of the saam node that you
created in step 2.
5. Create the deployment job:
ds job-create -t template_id -P "MGMNetInterface=net_interface"
-N "saam=saam_nodeid" saam-job

where

54

IBM Cloud Orchestrator 2.4.0.2: User's Guide

template_id
is the ID of the HA-saam template, which you identified in step 3 on
page 54.
net_interface
is the network interface that is used for communication between the
IBM Cloud Orchestrator management components: for example, eth0.
This value must be consistent on each node.
saam_nodeid
is the ID of the saam node, which you identified in step 4 on page 54.
If a problem occurs during job creation and the job status is WARNING or ERROR,
run the ds job-show <job ID> command to inspect the details of the job which
also include the related error message.
6. Run the deployment job:
ds job-execute saam-job

Results
System Automation Application Manager is installed in the high-availability
topology.

Installing the Central Servers

Use the HA-sco-central-servers-extdb template to install the Central Servers in
the high-availability topology.

Before you begin

The high availability setup requires the usage of an external database.
For more information about how to create the external databases and how to
register the database resources, see Configuring an external database on page 40.

Procedure
1. Create the following virtual machines with a supported operating system
installed, to be configured as the Central Servers:
v Central Server 1
v Central Server 2 primary
v Central Server 2 secondary
v Central Server 3
2. Create a node resource for each virtual machine, and register the resources in
the Deployment Service:
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password}"
central_server_1
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password}"
central_server_2p
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password}"
central_server_2s
Chapter 2. Installing

55

ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password}"
central_server3

where
IBM::SCO::Node
indicates that the virtual machine is registered as a node resource.
node_address
is the IP address of the virtual machine.
port

is the port number to access the virtual machine.

user_name
is the name of a root user on the virtual machine.
password
is the password for the specified root user on the virtual machine.
3. Run the ds template-list command to find the ID of the HA-sco-centralservers-extdb template.
4. Reregister the saam node installed in Installing System Automation Application
Manager on page 54 with a different name, for example, cs_saam. Run ds
node-create -t "IBM::SCO::Node" -p "{Address: saam_address, Port: 22,
User: root, Password: password }" cs_saam. Use the nodeid created there in
the subsequent ds job-create command.
5. Run the ds node-list command to find the IDs of the following resources:
v The System Automation Application Manager resource: saam
v The Central Server resources that you created in step 2 on page 55:
central_server_1
central_server_2p
central_server_2s
central_server_3
v The external database resources:
bpm_db
cmn_db
dashboard_db
keystone_db
metering_db
pdw_db
6. Create the deployment job. The parameters within the command must be
entered without any spaces. The parameters are shown on separate lines for
clarity:
job-create

56

-t <template_id>;
-P "CentralServer2VirtualAddress=<CentralServer2VirtualAddress>;
CentralServer2VirtualHostname=<CentralServer2VirtualHostname>;
CentralServer2VirtualNetmask=<CentralServer2VirtualNetmask>;
CentralServer2VirtualTieBreaker=<CentralServer2VirtualTieBreaker>;
MGMNetInterface=<net_interface>;
SingleSignOnDomain=<SingleSignOnDomain>;
OrchestratorPassword= External DB instance password"
-N "saam=<saam_nodeid>;
central_server_1=<central_server_1_nodeid>;
central_server_2_p=<central_server_2_p_nodeid>;
central_server_2_s=<central_server_2_s_nodeid>;

IBM Cloud Orchestrator 2.4.0.2: User's Guide

central_server_3=<central_server_3_nodeid>;
bpm_db=<bpm_db_nodeid>;
dashboard_db=<dashboard_db_nodeid>;
keystone_db=<keystone_db_nodeid>;
metering_db=<metering_db_nodeid>;
pdw_db=<pdw_db_nodeid>;
cmn_db=<cmn_db_nodeid>"
HA-sco-central-servers-extdb_job

where
<template_id>
Is the ID of the HA-sco-central-servers-extdb template, which you
identified in step 3 on page 56.
<CentralServer2VirtualAddress>
Is the virtual address to be used for Central Server 2. To achieve high
availability, this server is run on two instances. Each instance requires
its own IP address. The virtual address is an additional IP address,
which is assigned to the active virtual machine of a System Automation
for Multiplatforms cluster. If the primary virtual machine fails, the
virtual address is moved to the secondary virtual machine, and the
secondary virtual machine become the active virtual machine.
Applications access the services running on this high availability cluster
by using the virtual IP address.
Note: You must create the IP address in the DNS server, there is no
need that the virtual machine exists.
<CentralServer2VirtualHostname>
Is the host name of the virtual address to be used for Central Server 2.
It must be in FQDN format.
Note: CentralServer2VirtualHostname is the fully qualified domain
name (FQDN) of IP address of CentralServer2VirtualAddress in the
DNS server.
<CentralServer2VirtualNetmask>
Is the netmask of the virtual address to be used for Central Server 2.
<CentralServer2VirtualTieBreaker>
Is the IP address of the default gateway of the subnet that is used for
the virtual machines of the IBM Cloud Orchestrator management stack.
The System Automation for Multiplatforms cluster uses network
connectivity to this default network gateway to determine if a node is
still up and running. If a cluster split occurs, the tiebreaker determines
which part of the cluster gets quorum and can manage active resources.
For more information about quorums and tiebreakers, see Operational
quorum.
<net_interface>
Is the network interface that is used for communication between the
IBM Cloud Orchestrator management components: for example, eth0.
This value must be consistent on each node.
<SingleSignOnDomain>
Is the DNS domain name where the manage-from components are
installed. The manage-from components include IBM HTTP Server, IBM
Cloud Orchestrator user interfaces, Workload Deployer, and Business
Process Manager.
Chapter 2. Installing

57

<resource_nodeid>
Are the resource IDs that you identified in step 5 on page 56.
7. Run the deployment job:
ds job-execute HA-sco-central-servers-extdb_job

Results
The Central Servers are installed in the high-availability topology.
Related concepts:
Using the command-line interface to deploy IBM Cloud Orchestrator on page
198
You can use the command-line interface to deploy your IBM Cloud Orchestrator
environment.
Deployment parameters on page 213
Check the list of all deployment parameters that you can configure before
deploying IBM Cloud Orchestrator, and the parameter default values.
Configuring an external database on page 40
If you want to use an external database in your IBM Cloud Orchestrator
environment, you must configure it by following this procedure.

Installing the Region Server

Use one of the templates provided to install the Region Server in the
high-availability topology. You can install a KVM region or VMware region, and
each region can have Neutron network.

Before you begin

Before you start to install a Region Server, you must create the OpenStack database
on your external IBM DB2 installation. You must also create the following
database resources, and register the database resources in the Deployment Service:
v compute_db
v image_db
v network_db
v orchestration_db
v volume_db
Note: compute_db uses nova user, image_db uses glance user, network_db uses
neutron user, orchestration_db uses heat user and volume_db uses cinder user.
For more information about how to create the external database and how to
register the database resources, see Configuring an external database on page 40.

Installing a KVM Region Server with Neutron network

Use the HA-kvm_region-with-compute-neutron-extdb template to install a KVM
Region Server with Neutron network in the high-availability topology.

Before you begin

Create the external databases and register the database resources, as described in
Installing the Region Server.

58

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. Create four virtual machines with a supported operating system installed, to be
configured as the Region Server: KVM Region Server primary, KVM Region
Server secondary, KVM compute node, and Neutron network node.
2. Create a node resource for each virtual machine, and register the resources in
the Deployment Service:
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
kvm_region_server_p
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
kvm_region_server_s
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
kvm_compute
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
neutron_network_node

where
IBM::SCO::Node
indicates that the virtual machine is registered as a node resource.
node_address
is the IP address of the virtual machine.
port

is the port number to access the virtual machine.

user_name
is the name of a root user on the virtual machine.
password
is the password for the specified root user on the virtual machine.
3. Run the ds template-list command to find the ID of the HA-kvm_region-withcompute-neutron-extdb template.
4. Reregister the saam node installed in Installing System Automation Application
Manager on page 54 with a different name, for example, kvm_saam. Run ds
node-create -t "IBM::SCO::Node" -p "{Address: saam_address, Port: 22,
User: root, Password: password }" kvm_saam. Use the nodeid created there in
the subsequent ds job-create command.
5. Run the ds node-list command to find the IDs of the following resources:
v The System Automation Application Manager resource: kvm_saam that you
created in step 4.
v The Region Server resources that you created in step 2: kvm_region_server_p,
kvm_region_server_s, kvm_compute, and neutron_network_node.
v The external database resources: compute_db, image_db, network_db,
orchestration_db, and volume_db.
6. Run the ds job-list command to find the ID of the HA-sco-central-serversextdb_job job.
7. Create the deployment job:

Chapter 2. Installing

59

ds job-create -t template_id
-P "RegionServerVirtualAddress=RegionServerVirtualAddress;
RegionServerVirtualHostname=RegionServerVirtualHostname;
RegionServerVirtualNetmask=RegionServerVirtualNetmask;
RegionServerVirtualTieBreaker=RegionServerVirtualTieBreaker;
MGMNetInterface=net_interface;
OrchestratorPassword=External DB instance password"
-N "saam=saam_nodeid;
kvm_region_server_p=kvm_region_server_p_nodeid;
kvm_region_server_s=kvm_region_server_s_nodeid;
neutron_network_node=neutron_network_node_nodeid;
compute_db=compute_db_nodeid;
image_db=image_db_nodeid;
network_db=network_db_nodeid;
orchestration_db=orchestration_db_nodeid;
volume_db=volume_db_nodeid"
-p central_server_job_id
HA-kvm_region-with-compute-neutron-extdb_job

where
template_id
is the ID of the HA-kvm_region-neutron-extdb_job template, which you
identified in step 3 on page 59.
RegionServerVirtualAddress
Is the virtual address to be used for Region Server. To achieve high
availability, this server is run on two instances. Each instance requires
its own IP address. The virtual address is an additional IP address,
which is assigned to the active virtual machine of a System Automation
for Multiplatforms cluster. If the primary virtual machine fails, the
virtual address is moved to the secondary virtual machine, and the
secondary virtual machine become the active virtual machine.
Applications access the services running on this high availability cluster
by using the virtual IP address.
RegionServerVirtualHostname
is the host name of the virtual address to be used for the Region Server.
RegionServerVirtualNetmask
is the netmask of the virtual address to be used for the Region Server.
RegionServerVirtualTieBreaker
is the TieBreaker for the System Automation for Multiplatforms cluster
on the Region Server. If a cluster split occurs, the tiebreaker determines
which part of the cluster gets quorum and can manage active resources.
For example, you can use the gateway of the network as the tiebreaker.
For more information about quorums and tiebreakers, see Operational
quorum.
net_interface
is the network interface that is used for communication between the
IBM Cloud Orchestrator management components: for example, eth0.
This value must be consistent on each node.
OrchestratorPassword
is the password of the instance in the external database where the IBM
Cloud Orchestrator database is installed.
<X>_nodeid
are the resource IDs that you identified in step 5 on page 59.

60

IBM Cloud Orchestrator 2.4.0.2: User's Guide

central_server_job_id
is the ID of the HA-sco-central-servers-extdb_job job, which you
identified in step 6 on page 59.
If a problem occurs during job creation and the job status is WARNING or ERROR,
run the ds job-show <job ID> command to inspect the details of the job which
also include the related error message.
8. Run the deployment job:
ds job-execute HA-kvm_region-with-compute-neutron-extdb_job

Results
The KVM Region Server with Neutron network is installed in the high-availability
topology.

Installing a KVM Region Server with Nova network

Use the HA-kvm_region-with-compute-extdb template to install a KVM Region
Server with Nova network in the high-availability topology.

Before you begin

Create the external databases and register the database resources, as described in
Installing the Region Server on page 58.

Procedure
1. Create three virtual machines with a supported operating system installed, to
be configured as the Region Server: KVM Region Server primary, KVM Region
Server secondary, and KVM compute node.
2. Create a node resource for each virtual machine, and register the resources in
the Deployment Service:
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
kvm_region_server_p
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
kvm_region_server_s
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
kvm_compute

where
IBM::SCO::Node
indicates that the virtual machine is registered as a node resource.
node_address
is the IP address of the virtual machine.
port

is the port number to access the virtual machine.

user_name
is the name of a root user on the virtual machine.
password
is the password for the specified root user on the virtual machine.
Chapter 2. Installing

61

3. Run the ds template-list command to find the ID of the HA-kvm_region-withcompute-extdb template.

4. Reregister the saam node installed in Installing System Automation Application
Manager on page 54 with a different name, for example, kvm_saam. Run ds
node-create -t "IBM::SCO::Node" -p "{Address: saam_address, Port: 22,
User: root, Password: password }" kvm_saam. Use the nodeid created there in
the subsequent ds node-create command.
5. Run the ds node-list command to find the IDs of the following resources:
v The System Automation Application Manager resource: saam
v The Region Server resources that you created in step 2 on page 61:
kvm_region_server_p, kvm_region_server_s, and kvm_compute
v The external database resources: compute_db, image_db, network_db,
orchestration_db, and volume_db
6. Run the ds job-list command to find the ID of the HA-sco-central-serversextdb_job job.
7. Create the deployment job:
ds job-create -t template_id
-P "RegionServerVirtualAddress=RegionServerVirtualAddress;
RegionServerVirtualHostname=RegionServerVirtualHostname;
RegionServerVirtualNetmask=RegionServerVirtualNetmask;
RegionServerVirtualTieBreaker=RegionServerVirtualTieBreaker;
MGMNetInterface=net_interface;
OrchestratorPassword=External DB instance password"
-N "saam=saam_nodeid;
kvm_region_server_p=kvm_region_server_p_nodeid;
kvm_region_server_s=kvm_region_server_s_nodeid;
kvm_compute=kvm_compute_nodeid;
compute_db=compute_db_nodeid;
image_db=image_db_nodeid;
network_db=network_db_nodeid;
orchestration_db=orchestration_db_nodeid;
volume_db=volume_db_nodeid"
-p central_server_job_id
HA-kvm_region-neutron-extdb_job

where
template_id
is the ID of the HA-kvm_region-with-compute-extdb template, which
you identified in step 3.
RegionServerVirtualAddress
Is the virtual address to be used for Region Server. To achieve high
availability, this server is run on two instances. Each instance requires
its own IP address. The virtual address is an additional IP address,
which is assigned to the active virtual machine of a System Automation
for Multiplatforms cluster. If the primary virtual machine fails, the
virtual address is moved to the secondary virtual machine, and the
secondary virtual machine become the active virtual machine.
Applications access the services running on this high availability cluster
by using the virtual IP address.
RegionServerVirtualHostname
is the host name of the virtual address to be used for the Region Server.
RegionServerVirtualNetmask
is the netmask of the virtual address to be used for the Region Server.

62

IBM Cloud Orchestrator 2.4.0.2: User's Guide

RegionServerVirtualTieBreaker
is the TieBreaker for the System Automation for Multiplatforms cluster
on the Region Server. If a cluster split occurs, the tiebreaker determines
which part of the cluster gets quorum and can manage active resources.
For example, you can use the gateway of the network as the tiebreaker.
For more information about quorums and tiebreakers, see Operational
quorum.
net_interface
is the network interface that is used for communication between the
IBM Cloud Orchestrator management components: for example, eth0.
This value must be consistent on each node.
OrchestratorPassword
is the password of the instance in the external database where the IBM
Cloud Orchestrator database is installed.
<X>_nodeid
are the resource IDs that you identified in step 5 on page 62.
central_server_job_id
is the ID of the HA-sco-central-servers-extdb_job job, which you
identified in step 6 on page 62.
If a problem occurs during job creation and the job status is WARNING or ERROR,
run the ds job-show <job ID> command to inspect the details of the job which
also include the related error message.
8. Run the deployment job:
ds job-execute HA-kvm_region-with-compute-extdb_job

Results
The KVM Region Server with Nova network is installed in the high-availability
topology.

Installing a VMware Region Server with Neutron network

Use the HA-vmware_region-neutron-extdb template to install a VMware Region
Server with Neutron network in the high-availability topology.

Before you begin

Create the external databases and register the database resources, as described in
Installing the Region Server on page 58.

Procedure
1. Create three virtual machines with a supported operating system installed, to
be configured as the Region Server: VMware Region Server primary, VMware
Region Server secondary, and Neutron network node.
2. Create a node resource for each virtual machine, and register the resources in
the Deployment Service:
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
vmware_region_server_p
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
Chapter 2. Installing

63

vmware_region_server_s
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
neutron_network_node

where
IBM::SCO::Node
indicates that the virtual machine is registered as a node resource.
node_address
is the IP address of the virtual machine.
port

is the port number to access the virtual machine.

user_name
is the name of a root user on the virtual machine.
password
is the password for the specified root user on the virtual machine.
3. Run the ds template-list command to find the ID of the HA-vmware_regionneutron-extdb template.
4. Reregister the saam node installed in Installing System Automation Application
Manager on page 54 with a different name, for example, vmware_n_saam. Run
ds node-create -t "IBM::SCO::Node"
-p "{Address: saam_address, Port: 22, User: root, Password: password }"
vmware_n_saam

. Use the nodeid created there in the subsequent ds node-create command.

5. Run the ds node-list command to find the IDs of the following resources:
v The System Automation Application Manager resource: vmware_n_saam as
specified in the previous step.
v The Region Server resources that you created in step 2 on page 63:
vmware_region_server_p, vmware_region_server_s, and
neutron_network_node.
v The external database resources: compute_db, image_db, network_db,
orchestration_db, and volume_db.
6. Run the ds job-list command to find the ID of the HA-sco-central-serversextdb_job job.
7. Create the deployment job:
ds job-create -t template_id
-P "RegionServerVirtualAddress=RegionServerVirtualAddress;
RegionServerVirtualHostname=RegionServerVirtualHostname;
RegionServerVirtualNetmask=RegionServerVirtualNetmask;
RegionServerVirtualTieBreaker=RegionServerVirtualTieBreaker;
VMServerHost=VMServerHost;
VMServerUserName=VMServerUserName;
VMServerPassword=VMServerPassword;
VMClusterName=VMClusterName;
MGMNetInterface=net_interface"
-N "saam=saam_nodeid;
vmware_region_server_p=vmware_region_server_p_nodeid;
vmware_region_server_s=vmware_region_server_s_nodeid;
neutron_network_node=neutron_network_node_nodeid;
compute_db=compute_db_nodeid;
image_db=image_db_nodeid;
network_db=network_db_nodeid;
orchestration_db=orchestration_db_nodeid;

64

IBM Cloud Orchestrator 2.4.0.2: User's Guide

volume_db=volume_db_nodeid"
-p central_server_job_id
HA-vmware_region-neutron-extdb_job

where
template_id
is the ID of the HA-vmware_region-neutron-extdb template, which you
identified in step 3 on page 64.
RegionServerVirtualAddress
Is the virtual address to be used for Region Server. To achieve high
availability, this server is run on two instances. Each instance requires
its own IP address. The virtual address is an additional IP address,
which is assigned to the active virtual machine of a System Automation
for Multiplatforms cluster. If the primary virtual machine fails, the
virtual address is moved to the secondary virtual machine, and the
secondary virtual machine become the active virtual machine.
Applications access the services running on this high availability cluster
by using the virtual IP address.
RegionServerVirtualHostname
is the host name of the virtual address to be used for the Region Server.
RegionServerVirtualNetmask
is the netmask of the virtual address to be used for the Region Server.
RegionServerVirtualTieBreaker
is the TieBreaker for the System Automation for Multiplatforms cluster
on the Region Server. If a cluster split occurs, the tiebreaker determines
which part of the cluster gets quorum and can manage active resources.
For example, you can use the gateway of the network as the tiebreaker.
For more information about quorums and tiebreakers, see Operational
quorum.
VMServerHost
is the IP address of the vCenter server.
VMServerUserName
is the name of a user on the vCenter server.
VMServerPassword
is the password for the specified user on the vCenter server.
VMClusterName
is the cluster name in vCenter that is used to start the virtual machine.
net_interface
is the network interface that is used for communication between the
IBM Cloud Orchestrator management components: for example, eth0.
This value must be consistent on each node.
<X>_nodeid
are the resource IDs that you identified in step 5 on page 64.
central_server_job_id
is the ID of the HA-sco-central-servers-extdb_job job, which you
identified in step 6 on page 64.
OrchestratorPassword
is the password of the instance in the external database where the IBM
Cloud Orchestrator database is installed.

Chapter 2. Installing

65

If a problem occurs during job creation and the job status is WARNING or ERROR,
run the ds job-show <job ID> command to inspect the details of the job which
also include the related error message.
You can run the ds template-parameters-list HA-vmware_region-neutronextdb command to get the list of the parameters that you can specify for the
HA-vmware_region-neutron-extdb template.
8. Run the deployment job:
ds job-execute HA-vmware_region-neutron-extdb_job

Results
The VMware Region Server with Neutron network is installed in the
high-availability topology.

Installing a VMware Region Server with Nova network

Use the HA-vmware_region-extdb template to install a VMware Region Server with
Nova network in the high-availability topology.

Before you begin

Create the external databases and register the database resources, as described in
Installing the Region Server on page 58.

Procedure
1. Create two virtual machines with a supported operating system installed, to be
configured as the Region Server: VMware Region Server primary and VMware
Region Server secondary.
2. Create a node resource for each virtual machine, and register the resources in
the Deployment Service:
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
vmware_region_server_p
ds node-create -t "IBM::SCO::Node"
-p "{Address: node_address, Port: port,
User: user_name, Password: password }"
vmware_region_server_s

where
IBM::SCO::Node
indicates that the virtual machine is registered as a node resource.
node_address
is the IP address of the virtual machine.
port

is the port number to access the virtual machine.

user_name
is the name of a root user on the virtual machine.
password
is the password for the specified root user on the virtual machine.
3. Run the ds template-list command to find the ID of the HA-vmware_regionextdb template.
4. Reregister the saam node installed in Installing System Automation Application
Manager on page 54 with a different name, for example, vmware_saam. Run ds

66

IBM Cloud Orchestrator 2.4.0.2: User's Guide

node-create -t "IBM::SCO::Node" -p "{Address: saam_address, Port: 22,

User: root, Password: password }" vmware_saam. Use the nodeid created there
in the subsequent ds node-create command.
5. Run the ds node-list command to find the IDs of the following resources:
v The System Automation Application Manager resource: saam
v The Region Server resources that you created in step 2 on page 66:
vmware_region_server_p and vmware_region_server_s
v The external database resources: compute_db, image_db, network_db, nova_db,
orchestration_db, and volume_db
6. Run the ds job-list command to find the ID of the HA-sco-central-serversextdb_job job.
7. Create the deployment job:
ds job-create -t template_id
-P "RegionServerVirtualAddress=RegionServerVirtualAddress;
RegionServerVirtualHostname=RegionServerVirtualHostname;
RegionServerVirtualNetmask=RegionServerVirtualNetmask;
RegionServerVirtualTieBreaker=RegionServerVirtualTieBreaker;
VMServerHost=VMServerHost;
VMServerUserName=VMServerUserName;
VMServerPassword=VMServerPassword;
VMClusterName=VMClusterName;
MGMNetInterface=net_interface;
OrchestratorPassword=External DB instance password"
-N "saam=saam_nodeid;
vmware_region_server_p=vmware_region_server_p_nodeid;
vmware_region_server_s=vmware_region_server_s_nodeid;
compute_db=compute_db_nodeid;
image_db=image_db_nodeid;
network_db=network_db_nodeid;
nova_db=nova_db_nodeid;
orchestration_db=orchestration_db_nodeid;
volume_db=volume_db_nodeid"
-p central_server_job_id
HA-vmware_region-extdb_job

where
template_id
is the ID of the HA-vmware_region-extdb template, which you identified
in step 3 on page 66.
RegionServerVirtualAddress
Is the virtual address to be used for Region Server. To achieve high
availability, this server is run on two instances. Each instance requires
its own IP address. The virtual address is an additional IP address,
which is assigned to the active virtual machine of a System Automation
for Multiplatforms cluster. If the primary virtual machine fails, the
virtual address is moved to the secondary virtual machine, and the
secondary virtual machine become the active virtual machine.
Applications access the services running on this high availability cluster
by using the virtual IP address.
RegionServerVirtualHostname
is the host name of the virtual address to be used for the Region Server.
RegionServerVirtualNetmask
is the netmask of the virtual address to be used for the Region Server.
RegionServerVirtualTieBreaker
is the TieBreaker for the System Automation for Multiplatforms cluster
Chapter 2. Installing

67

on the Region Server. If a cluster split occurs, the tiebreaker determines

which part of the cluster gets quorum and can manage active resources.
For example, you can use the gateway of the network as the tiebreaker.
For more information about quorums and tiebreakers, see Operational
quorum.
VMServerHost
is the IP address of the vCenter server.
VMServerUserName
is the name of a user on the vCenter server.
VMServerPassword
is the password for the specified user on the vCenter server.
VMClusterName
is the cluster name in vCenter that is used to start the virtual machine.
net_interface
is the network interface that is used for communication between the
IBM Cloud Orchestrator management components: for example, eth0.
This value must be consistent on each node.
OrchestratorPassword
is the password of the instance in the external database where the IBM
Cloud Orchestrator database is installed.
<X>_nodeid
are the resource IDs that you identified in step 5 on page 67.
central_server_job_id
is the ID of the HA-sco-central-servers-extdb_job job, which you
identified in step 6 on page 67.
If a problem occurs during job creation and the job status is WARNING or
ERROR, run the ds job-show <job ID> command to inspect the details of the
job which also include the related error message.
You can run the ds template-parameters-list HA-vmware_region-extdb
command to get the list of the parameters that you can specify for the
HA-vmware_region-extdb template.
8. Run the deployment job:
ds job-execute HA-vmware_region-extdb_job

Results
The VMware Region Server with Nova network is installed in the high-availability
topology.

Verifying the installation

When you have completed the installation of your IBM Cloud Orchestrator
environment (Central Servers and Region Servers), you can verify the installation
by completing the following steps.

Procedure
1. Verify that you can access and log in to the following IBM Cloud Orchestrator
user interfaces:
v Self-service user interface

68

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Administration user interface

v Business Process Manager user interface
To access each user interface, use the admin user and the IBM Cloud
Orchestrator password that you specified with the OrchestratorPassword
parameter in the deployment template. Use the Default domain name.
For information about accessing the IBM Cloud Orchestrator user interfaces, see
Accessing IBM Cloud Orchestrator user interfaces on page 222.
2. Verify that the Self-Service Catalog is populated. In the Self-service user
interface, click SELF-SERVICE CATALOG and navigate the built-in categories
and the associated offerings.
3. Verify that the status of the IBM Cloud Orchestrator components is correct.
v If you installed IBM Cloud Orchestrator as highly available, log on to the
System Automation Application Manager interface and verify that the root
resource named Cloud Orchestrator shows the following states:
Compound State OK
Observed State Online
Desired State Online
Automated Yes

Note: For more information, see Using System Automation Application

Manager on page 238.
v If you installed IBM Cloud Orchestrator as not highly available, run the
following command on Central Server 1:
/opt/ibm/orchestrator/scorchestrator/SCOrchestrator.py --status

Verify that the status of each IBM Cloud Orchestrator component is online,
as shown in the following example output:
===>>> Collecting Status for IBM Cloud Orchestrator
===>>> Please wait ======>>>>>>
Component
Hostname
Status
------------------------------------------------------------------bpm-dmgr
192.0.2.84
online
bpm-node
192.0.2.84
online
bpm-server
192.0.2.84
online
db2
192.0.2.83
online
iwd
192.0.2.87
online
openstack-ceilometer-api
192.0.2.84
online
openstack-ceilometer-api
192.0.2.83
online
openstack-ceilometer-central 192.0.2.83
online
openstack-ceilometer-collector 192.0.2.83
online
openstack-keystone
192.0.2.84
online
pcg
192.0.2.84
online
qpidd
192.0.2.83
online
swi
192.0.2.84
online
===>>> Status IBM Cloud Orchestrator complete

4. Verify the connectivity to each configured Region, by running the following

OpenStack commands on each Region Server and verifying that the output is
correct. For more information about the OpenStack command-line interface, see
the OpenStack User Guide.
Note: If you installed IBM Cloud Orchestrator as highly available, run the
steps on each primary Region Server.
a. Run the following command to invoke the profile:
source /root/openrc

b. Run the following command to display a list of services:

nova service-list
Chapter 2. Installing

69

If the environment is working, the state of each service is up, as shown in

the following example output for a VMware region:
+------------------+-----------------------+----------+---------+------| Binary
| Host
| Zone
| Status | State
+------------------+-----------------------+----------+---------+------| nova-conductor | vmware-region-europe1 | internal | enabled | up
| nova-scheduler | vmware-region-europe1 | internal | enabled | up
| nova-consoleauth | vmware-region-europe1 | internal | enabled | up
| nova-cert
| vmware-region-europe1 | internal | enabled | up
| nova-compute
| vmware-region-europe1 | nova
| enabled | up
| nova-vmware
| vmware-region-europe1 | internal | enabled | up
+------------------+-----------------------+----------+---------+------+----------------------------+-----------------+
| Updated_at
| Disabled Reason |
+----------------------------+-----------------+
| 2014-07-23T10:15:05.295438 | |
| 2014-07-23T10:15:05.956364 | |
| 2014-07-23T10:15:05.929082 | |
| 2014-07-23T10:15:05.284974 | |
| 2014-07-23T10:15:02.814094 | |
| 2014-07-23T10:15:05.954436 | |
+----------------------------+-----------------+

c. Check the hypervisor status as follows:

1) Identify the ID of the hypervisor:
nova hypervisor-list

2) Display the hypervisor status:

nova hypervisor-show hypervisor_id

The following example output is for a VMware region:

+----+---------------------+
| ID | Hypervisor hostname |
+----+---------------------+
| 1 | domain-c7(europe-1) |
+----+---------------------+
+---------------------------+-----------------------------------------------+
| Property
| Value
|
+---------------------------+-----------------------------------------------+
| cpu_info_model
| ["Intel(R) Xeon(R) CPU X5570 @ 2.93GHz",
|
|
| "Intel(R) Xeon(R) CPU X5570 @ 2.93GHz"]
|
| cpu_info_topology_cores | 16
|
| cpu_info_topology_threads | 32
|
| cpu_info_vendor
| ["IBM", "IBM"]
|
| current_workload
| 0
|
| disk_available_least
| |
| free_disk_gb
| 679
|
| free_ram_mb
| 60755
|
| host_ip
| 192.0.2.16
|
| hypervisor_hostname
| domain-c7(europe-1)
|
| hypervisor_type
| VMware vCenter Server
|
| hypervisor_version
| 5001000
|
| id
| 1
|
| local_gb
| 959
|
| local_gb_used
| 280
|
| memory_mb
| 89939
|
| memory_mb_used
| 29184
|
| running_vms
| 11
|
| service_host
| vmware-region-europe1
|
| service_id
| 8
|
| vcpus
| 32
|
| vcpus_used
| 14
|
+---------------------------+-----------------------------------------------+

5. Verify the infrastructure status by checking that you have availability zones
created. In the Administration user interface, click Admin > System Panel >
Host Aggregates, and verify that the Availability Zones list is populated.
Note: If you have a multiregion environment, you can switch between regions
by using the dropdown list in the upper-right corner of the window. The
regions that you see in the Administration user interface are not the same as

70

IBM Cloud Orchestrator 2.4.0.2: User's Guide

the ones listed in the output of the keystone endpoint list because the keystone
command output includes RegionCentral, an OpenStack region that is used
only by Ceilometer.

What to do next
Before you can use IBM Cloud Orchestrator to manage your cloud environment,
you must configure your environment as described in Post-installation tasks on
page 72. At a minimum, you must complete the following basic configuration
tasks:
1. Assign zones to domains and projects, as described in Assigning zones to
domains and projects on page 72.
2. Configure your network, as described in Managing Nova networks on page
88 or Managing Neutron networks on page 93.
You can then test the configuration by creating and registering an image, and then
deploying the image to a region, as described in Chapter 6, Managing virtual
images, on page 331.

Installing IBM Cloud Orchestrator Enterprise Edition

For more control over your cloud environment, IBM Cloud Orchestrator Enterprise
Edition bundles three additional products.
v Jazz for Service Management
v IBM Tivoli Monitoring
v IBM SmartCloud Cost Management
These components can be installed on physical or virtual machines, subject to the
relevant hardware and software requirements. For more information about these
components, visit the following links:
v Quick Start Guide for Jazz for Service Management.
v Quick Start Guide for IBM SmartCloud Cost Management
v Quick Start Guide for IBM Tivoli Monitoring and Tivoli Monitoring for Virtual
Environments

Installation procedure
The first part of the IBM Cloud Orchestrator Enterprise Edition installation is
exactly the same as for the base version. Then you must install the additional
products on separate machines:
1. Refer to the installation procedure in the Chapter 2, Installing, on page 15
section to install IBM Cloud Orchestrator and its services.
2. Install Jazz for Service Management V1.1.0.1. For instructions, see the Jazz for
Service Management V1.1.0.1 Quick Start Guide.
3. Install IBM Tivoli Monitoring V6.3.0.2. For instructions, see Installing IBM
Tivoli Monitoring on page 718.
4. [Optional] Install IBM Tivoli Monitoring for Virtual Environments V7.2.0.2. For
instructions, see IBM Tivoli Monitoring for Virtual Environments Quick Start
Guide.
5. Install IBM SmartCloud Cost Management V2.1.0.4. For instructions, see Quick
start guide for metering and billing on page 72.

Chapter 2. Installing

71

Quick start guide for metering and billing

Use this topic as a start guide when configuring SmartCloud Cost Management for
metering and billing.
The following list provides information about configuration steps required for
metering and billing:
Install Tivoli Common Reporting 3.1.0.1
For information about this task, see the installing Tivoli Common
Reporting section in the Jazz for Service Management information center.
Install SmartCloud Cost Management
For information about this task, see Installing SmartCloud Cost
Management 2.1.0.4.
Configuration required for metering
For more information about the configuration required for metering, see
the Automated configuration topic.
Configure job processing
v For information about configuring processing paths, see the setting
processing options topic.
v For information about defining rates and rate templates. see
Administering the system.
v For information about customizing jobs, see Administering data
processing.

Post-installation tasks
After you install IBM Cloud Orchestrator, complete these additional configuration
steps and management tasks.
Note: Remember to update the Red Hat Enterprise Linux image to the appropriate
version to ensure that you avoid the Heartbleed vulnerability. For information
about the Heartbleed vulnerability, see https://access.redhat.com/solutions/
781793.

Assigning zones to domains and projects

Assign a zone to a domain and to a project after you complete the installation of
IBM Cloud Orchestrator.
To assign a zone, you must log in to the Administration user interface as Cloud
Administrator. Follow the steps described in Assigning a zone to a domain on
page 262 and Assigning a zone to a project on page 267.

Configuring LDAP authentication

Configure IBM Cloud Orchestrator to use an LDAP server for user authentication.
By default, IBM Cloud Orchestrator authenticates users against the OpenStack
Keystone database that is part of the product. You can configure IBM Cloud
Orchestrator to authenticate against an external corporate directory (such as LDAP
or Active Directory) by enabling IBM Cloud Orchestrator to pass an authentication
request to the corporate directory before passing the request to Keystone.
The LDAP authentication support provided by IBM Cloud Orchestrator enables
users defined in LDAP to logon to IBM Cloud Orchestrator by specifying the

72

IBM Cloud Orchestrator 2.4.0.2: User's Guide

LDAP credentials (user name and password) if configured correctly. However,

users defined locally in OpenStack Keystone are not populated into LDAP.
If you have a single corporate directory server which contains all the users
irrespective of which domain they are in, then follow the procedure described in
Configuring LDAP authentication independently of the domain.
In a multidomain configuration, IBM Cloud Orchestrator extends the
pre-authentication capability to allow any corporate directory details to be
specified on a domain-by-domain basis. In this mode, for any domain that requires
separate corporate directory details, you can define a specific partial Keystone
configuration file in addition to the main Keystone configuration file that is used
by all the domains. To configure LDAP authentication for a specific domain, follow
the procedure described in Configuring LDAP authentication on a
domain-by-domain basis on page 76.

Configuring LDAP authentication independently of the domain

You can configure LDAP authentication for IBM Cloud Orchestrator.
To configure LDAP authentication, you must already have an LDAP server set up.
You must specify which LDAP attributes are used as part of the authentication
process. Consider the following items:
v Which LDAP attribute is checked against the user name as part of
authentication? The default is the common name (cn) attribute, but you can
choose whatever suits your environment, for instance, email is a common
alternative. Whatever you chose here, is what the user must type into the IBM
Cloud Orchestrator login panel.
Where are the user objects stored in the LDAP server? You must specify the
root of the subtree that contains these user objects. They do not need to exists at
the same level, but they do need to be all within one subtree.
v Does your LDAP server support anonymous query? If not, you need an LDAP
user and password account that does have search capabilities, for the subtree
that contains the user's objects.

Note: The IBM Cloud Orchestrator administrator account admin already exists in
the local OpenStack database. Make sure that there is not an LDAP account that
also has the name admin, or this supersedes the local admin account.
After establishing these items, perform the following steps to configure LDAP
authentication:
1. Make sure that the ldapauth.py file exists in your Keystone installation in the
keystone/middleware directory.
2. The following properties can be defined in your Keystone configuration file to
control LDAP authentication. Comment the existing [ldap] section before you
add an [ldap_pre_auth] section. The keystone configuration file is, by default,
to be found in /etc/keystone/keystone.conf on Central Server 2:
[ldap_pre_auth]
# The url of the corporate directory server
url = ldap://localhost
# The root of the tree that contains the user records
user_tree_dn = cn=users,dc=example,dc=com
# The property in the user record that will be checked against the username
user_name_attribute = cn
# In order to search for user records, we will try and use anonymous query.
# If anonymous query is not available, then define the user and password
# of an account that does have rights to do a search
Chapter 2. Installing

73

user = cn=admin,cn=users,dc=example,dc=com
password = <admin_password>
# Define this property if you want to customize the user id
# which will be used if we automatically populate the user to keystone
user_id_attribute = dn
# By default if we fail to find a user in LDAP, we will then try and
# find that user directly in keystone. If you dont want that to happen
# then set pass_through to False
#pass_through = False

3. You can configure support for LDAP SSL or TLS. To use SSL, you must
configure the underlying openldap client with the appropriate certificate details
which are typically stored in /etc/openldap/ldap.conf, for example:
TLS_CACERT /etc/openldap/certs/serverkey.cer
TLS_REQCERT DEMAND

With openldap configured, you can refer to your secure LDAP server by
specifying url = ldaps://.... in keystone.conf.
If you use TLS, then the certificate details are specified in the keystone.conf
file itself:
[ldap_pre_auth]
tls_cacertfile = /path/to/certfile
tls_cacertdir = /path/to/certdir
tls_req_cert = demand
use_tls = True

tls_cacertfile and tls_cacertdir are not both required. If you use TLS, you
must use the regular url = ldap://.... connection specification (and not use
ldaps).
4. The LDAP objects that are checked during authentication can be restricted
using two variables in the configuration file. user_objectclass allows you to
specify the class of objects to be checked and user_filter allows you to specify
additional AND filters to be used in the objects being checked. For instance, the
following statement restricts authentication to objects of class person that have
an attribute memberOf indicating membership to an existing OpenStack group in
your corporate directory server:
[ldap_pre_auth]
user_objectclass = person
user_filter = (memberOf=CN=OpenStack,dc=ldap,dc=com)

5. In your Keystone paste configuration file, keystone-paste.ini by default,

define a filter for this class:
[filter:ldapauth]
paste.filter_factory = keystone.middleware.ldapauth:LdapAuthAuthentication.factory

6. Comment the existing pipeline and add the following line in the
keystone-paste.ini file:
[pipeline:api_v3]
#pipeline = access_log sizelimit url_normalize token_auth admin_token_auth xml_body json_body
#
simpletoken ec2_extension s3_extension service_v3
pipeline = access_log sizelimit stats_monitoring url_normalize token_auth admin_token_auth
xml_body json_body simpletoken ldapauth autopop debug stats_reporting ec2_extension
s3_extension service_v3

This procedure enables authentication to occur against your corporate directory.

However, a representation of an authenticated user must also be available in
Keystone after authorization so that, for example, roles can be assigned to the user.
While you can do this manually, or using an external directory synchronization
tool, IBM Cloud Orchestrator provides you with an auto-population plug-in that
can help you perform simple, automatic population of an LDAP user to Keystone
when that user first authenticates successfully to LDAP. The plug-in only

74

IBM Cloud Orchestrator 2.4.0.2: User's Guide

populates the minimal amount of information required into Keystone, that is, user
name and user ID. Because the plug-in does not propagate the user password,
these Keystone user entries do not allow the LDAP authentication step to be
bypassed. They are only present to allow role assignment. To configure
auto-population, you need to make the following choices:
v Which LDAP attribute is used to create a unique user_id within
the OpenStack keystone? This must be something that does not change over
time, that is limited to 64 characters, and that does not contain blank space
characters. The default is the distinguished name (DN) attribute, but you can
chose whatever suits your environment, for example, the email attribute is a
common alternative. It is acceptable, for example, to use email as both the
username and the user_id).
v Which project must the user be given an initial role on as part of the
auto-population? This project already needs to exist before the auto-population
takes place.
Note: It is not recommended that you enable a situation where a user sometimes
authenticates with LDAP and sometimes directly with Keystone, since unless these
are carefully maintained, with matching user_ids and so forth, this can cause
confusion about which is the master user record.
Note: The auto-population plug-in is not a replacement for a full directory
synchronization capability. While the plug-in creates a user-record the first time a
user authenticates, it does not, for example, delete that user record in keystone if
the LDAP user record is subsequently deleted. Such a user would indeed no longer
be able to log in to IBM Cloud Orchestrator, but the database cleanup is outside of
the scope of the auto-population plug-in. If such a full capability is required, then
the use of an external directory synchronization tool is recommended (for details
refer to Using external Directory Integration tools with LDAP authentication on
page 77).
1. Make sure the autopop.py file exists in your Keystone installation in the
keystone/middleware directory.
2. The main job of the auto-population plug-in is to ensure that a user record is
created in Keystone, so that subsequent role assignments can take place.
However, optionally, the plug-in can grant an initial role to that user. This is
achieved by specifying the project and role required in an [auto_population]
section of the configuration file. First, you must specify the project, by
providing either a project ID by defining default_project_id or a project name
by defining default_project. If a project name is specified, then this is
assumed to be in the same domain as the user who has just been authenticated,
whereas a project ID is, by definition, unique across all domains. For example:
[auto_population]
default_project = test-project

instructs the auto population plug-in to assign the authenticated user the
standard membership role in the project named test-project in the user's
domain. This project must already exist for this role assignment to take place.
Additionally, you can ask for the plug-in to grant a further explicit role to the
user on the project by specifying either a role name using a default_role or a
role ID using default_role_id. Hence, the following gives an authenticated
user both the membership role and the vm-manager role:
[auto_population]
default_project = test-project
default_role = vm-manager

Chapter 2. Installing

75

Note: The roles assigned here only affect the assignments held within IBM
Cloud Orchestrator and Keystone. They do not modify anything that is actually
stored in LDAP. The plug-in does not attempt to propagate any roles stored
explicitly within LDAP, although the use of an external directory
synchronization tool can enable such a capability.
Note: default_project_id is the standard config file variable for setting the
default project by ID.
3. In your Keystone paste configuration file, keystone-paste.ini by default,
define a filter for this class:
[filter:autopop]
paste.filter_factory = keystone.middleware.autopop:AutoPopulation.factory

4. Add the autopop plug-in to the pipeline that you are using, by default this is
the api_v3 pipeline. The plug-in autopop must come after the ldapauth filter:
[pipeline:api_v3]
pipeline = access_log sizelimit stats_monitoring url_normalize token_auth
admin_token_auth xml_body json_body simpletoken ldapauth autopop
debug stats_reporting ec2_extension s3_extension service_v3

5. In your Keystone policy configuration file, policy.json, modify the

list_user_projects parameter to allow users to list the projects they own, like:
"identity:list_user_projects": "rule:admin_or_owner_or_domain"

Configuring LDAP authentication on a domain-by-domain basis

There are some additional steps to configure LDAP authentication in an IBM
Cloud Orchestrator multidomain environment.
To specify corporate directory details on a domain-by-domain basis, perform the
following steps in addition to the procedure described in Configuring LDAP
authentication independently of the domain on page 73:
1. For each domain that needs its own corporate directory details, in the
<domain_config_files_dir> directory, you must create a domain-specific
configuration file with the following name:
keystone.<domain_name>.conf

Include only the [ldap_pre_auth] and [auto_population] sections in the

domain specific configuration file, within which you must define the specific
configuration for the LDAP server for that domain. The options available are
the same as those listed in topic Configuring LDAP authentication
independently of the domain on page 73.
2. Add the following properties in your Keystone configuration file:
[ldap_pre_auth]
domain_specific_drivers_enabled = True
domain_config_dir = <domain_config_files_dir>

where <domain_config_files_dir> is the directory where the domain specific

configuration files are stored.
Note: TLS certification details cannot currently be specified on a
domain-by-domain basis.

76

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Using external Directory Integration tools with LDAP

authentication
An alternative approach to using the provided auto-populate function is to use a
directory synchronization product, such as, for example, Tivoli Directory Integrator.
The configuration of this external capability depends on the specific product,
however you must perform the following steps:
1. In the user table in the Keystone SQL database, insert a record for each valid
LDAP or Active Directory that you want to use with the product. The structure
of the user table is as follows:
id
name
domain_id
password
enabled
extra

character
character
character
character
Boolean
text

varying(64) NOT NULL

varying(64) NOT NULL
varying(64) NOT NULL
varying(128) NOT NULL

where:
id

Must be unique across all user entries in Keystone. For example, it

might be the dn of the LDAP user.

name

Is the user name that is used for authentication.

domain_id
Must match the domain_id for the domain the user is in. If you have
not created any domains, this is the default domain for which the
domain_id is default. If you are using multiple domains, then the
domain_id must match the entry in the domains table.
password
This is not used for authentication, since that is done against the
corporate directory, so this must be set to some randomly generated
string to prevent the user from bypassing the corporate directory
authentication.
enabled
Must be set to true.
extra Can be left blank.
2. If the directory synchronization tool is used to delete user entries from the
Keystone database in response to a deletion in the corporate directory, then
there are a number of tables that must be updated and the user entry described
above must finally be deleted. Since a number of these tables use foreign keys
to point back to the user table, it is important that you only delete the user
entry itself once all the changes listed below have been made.
In the following tables you must delete any entry with a user_id that matches
the ID from the user table:
Table: UserProjectGrant:
user_id
character varying(64) NOT NULL
project_id
character varying(64) NOT NULL
data
text
Table: UserDomainGrant:
user_id
character varying(64) NOT NULL
domain_id
character varying(64) NOT NULL
data
text
Table: UserGroupMembership:
user_id
character varying(64) NOT NULL
group_id
character varying(64) NOT NULL
Chapter 2. Installing

77

If you are using an SQL server to store tokens, then to ensure that the user
being deleted is denied access to the product as soon as possible, the
TokenModel table must also be updated. If you are archiving expired tokens for
auditing purposes, then set the valid field to False for any token record that
matches the user_id. If you are not concerned about token archiving, you can
simple delete any token records that match this user_id.
Table: TokenModel:
id
character varying(64) NOT NULL
expires
datetime
extra
text
valid
boolean
user_id
character varying(64) NOT NULL
trust_id
character varying(64) NOT NULL

If using memcache as a token store, to disable a deleted LDAP user as soon as

possible, the memcache entries of tokens for that user must be deleted. The
memcache token store has two types of entries, with the keys of:
'usertokens-<user_id>'
Contains a list of token IDs for the user with the ID specified by
<user_id>
'tokens-<token_id>'
A specific token
To remove all tokens for a user, a memcache get must be issued for the key of
usertokens-<user_id> with the user_id in question. The value for this entry
is a list of token IDs, and for each of these delete the corresponding memcache
key of tokens-<token_id>. Finally, delete the key for usertokens<user_id>.

LDAP Keystone configuration file reference

The connection details of your corporate directory are stored within the
[ldap_pre_auth] and [auto-population] sections of either the keystone.conf file
or a domain specific configuration file.
The supported options within each of the two sections are the following:
Table 8. Configuration file options in ldap_pre_auth section
domain_config_dir

The directory that contains any domain specific configuration files. This is
only used if domain_specific_drivers_enabled is True.
Default
/etc/keystone/domains
Example
domain_config_dir = /etc/myconfigs

domain_specific_drivers_enabled

If True, then both the ldapauth and autopop plugins will look in the
domain_config_dir for domain specific configuration files of the form
keystone.<domainname>.conf, where <domainname>.conf is the name given to
the domain when it was created via the IBM Cloud Orchestrator UI.
Domain configuration files are only read when the keystone component of
IBM Cloud Orchestrator is started (or restarted).
Default
False

78

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 8. Configuration file options in ldap_pre_auth section (continued)

non_ldap_users

The local users are not authenticated with LDAP and they must be defined
via this option. The users defined in the list must already exist in the local
database. This option is required.
Default
None
Example
non_ldap_users = admin, demo, nova, neutron, cinder, glance,
monitoring, domadmin, heat, test

pass_through

If True, then if a user record is not found in the corporate directory server
that matches the specified user_name_attribute, then the authentication
request will be retried against the internal keystone database directly.
Default
True
Example
pass_through = False

password

The password for the user account specified by user to enable searching
within the corporate directory. This is unrelated to the actual user and the
password that is being authenticated.
Default
None
Example
password = secret

tls_cacertdir

The directory where TLS certificates are stored.

Default
None
Example
tls_cacertdir = /etc/openldap/cacertdir

tls_cacertfile

The TLS certification file itself.

Default
None
Example
tls_cacertfile = /etc/openldap/cacertdir/server.cer

tls_req_cert

The certificate requirement specification. This may be one of the following:

'never', 'demand' or 'allow'.
Default
None
Example
tls_req_cert = demand

Chapter 2. Installing

79

Table 8. Configuration file options in ldap_pre_auth section (continued)

The URL of the corporate directory server. If using SSL, you must also
configure the underlying openldap client with the certificate details. These
are typically stored in /etc/openldap/ldap.conf, for example:

url

TLS_CACERT /etc/openldap/certs/serverkey.cer
TLS_REQCERT ALLOW
With TLS, however, you configure these details in the keystone
configuration file itself (see the options tls_cacert and tls_req_cert
below), and use a regular ldap://... URL.
Default
None
Example
url = ldap://www.ibm.com/myserver
If using SSL, then use ldaps, for example:
url = ldaps://www.ibm.com/mysecureserver
The user account to be used for searching within the corporate directory.
This is unrelated to the actual user and password that is being
authenticated. If the corporate directory server supports anonymous query,
then this must not be specified.

user

Default
None
Example
user = cn=root
user_attribute_name

This is now deprecated, but has the same meaning as user_name_attribute.

Default
cn

user_filter

An additional filter (or filters) that will be ANDed into the search for the
user_name_attribute. The filter must be in brackets, as in the example.
Default
None
Example
user_filter = (memberOf=cn=openstack,dc=root)

user_id_attribute

If auto-population is enabled, this is the attribute that will be used as the

user_id when the keystone user record is created. A keystone user_id is
limited to 64 characters and must not contain blank space characters and
should be something that will not change for the lifetime of that user.
Default
dn
Example
user_id_attribute = mail

80

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 8. Configuration file options in ldap_pre_auth section (continued)

user_mail_attribute

If auto-population is enabled and it is required to propagate the email

address into the Keystone database, then define the attribute within the
corporate directory object to be used.
Default
None
Example
user_mail_attribute = mail

user_name_attribute

The attribute within each corporate directory object that will be compared
against the user name in the authentication request.
Default
cn
Example
user_name_attribute = mail

user_objectclass

The class of objects that will be searched to try and match the
user_name_attribute.
Default
*
Example
user_objectclass = person

user_tree_dn

The root of the subtree in the corporate directory server that will be
searched.
Default
cn=users,dc=example,dc=com
Example
user_tree_dn = cn=users,dc=root

use_tls

Indicates that the connection to the corporate directory should uses TLS.
Using an SSL LDAP connection (for example, url = ldaps://...) must not
be used as well as TLS.
Default
False
Example
use_tls = True

Table 9. Configuration file options in auto-population section

default_project

The default project to be assigned to the new user being created, which
means a member role will be given to this project for the user. The project
must already exist. Note that this project must exist in the same domain as
the user being created. If you want to assign the user a role in a project that
is in a different domain, then use default_project_id.
Default
None
Example
default_project = project1
Chapter 2. Installing

81

Table 9. Configuration file options in auto-population section (continued)

default_project_id

The default project ID to be assigned to the new user being created, which
means a member role will be given to this project for the user. The project
must already exist.
Default
None
Example
default_project_id = 87bb06e36a854c0b97c45b4e6dbf5ee4
An additional role (specified by name) that will be granted to the newly
created user on the default project (in addition to the member role).

default_role

Default
None
Example
default_role = vm-manager
default_role_id

An additional role (specified by ID) that will be granted to the newly

created user on the default project (in addition to the member role).
Default
True
Example
default_role_id= 34bc06e13a854c0b97c45b4e66bf5fe1

default_tenant_id

This is now deprecated, but has the same meaning as default_project_id.

Default
None

Configuring Single Sign On to IBM Cloud Orchestrator

With Single Sign On (SSO), users authenticate once to an authentication service,
and subsequently are logged in automatically to all web applications that support
the chosen SSO mechanism. Popular SSO mechanisms include Microsofts
SPNEGO/Kerberos authentication, Websphere Application Servers native
LtpaToken, and open standards like OpenID.

About this task

IBM Cloud Orchestrator uses WebSphere Application Servers authentication
infrastructure to perform SSO. Refer to the WebSphere Application Server
documentation for steps to setup SSO:
v For SPNEGO/Kerberos based authentication, refer to: http://www-01.ibm.com/
support/knowledgecenter/SSAW57_8.5.5/com.ibm.websphere.nd.doc/ae/
tsec_kerb_setup.html?cp=SSAW57_8.5.5%2F1-3-0-22&lang=en.
v For custom SSO implementations, refer to : http://www-01.ibm.com/support/
knowledgecenter/SSAW57_8.5.5/com.ibm.websphere.nd.doc/ae/
tsec_SPNEGO_overview.html?cp=SSAW57_8.5.5%2F1-3-0-21&lang=en.
v For LTPA based implementations, refer to: http://www-01.ibm.com/support/
knowledgecenter/SSAW57_8.5.5/com.ibm.websphere.nd.doc/ae/
tsec_ltpa_and_keys_step4.html?cp=SSAW57_8.5.5%2F1-3-0-19-3&lang=en.

82

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Avoiding troubles
Some SSO plugins redirect an HTTP call or return an Unauthenticated message
when the client does not authenticate using the configured SSO method. IBM
Cloud Orchestrator relies on internal communication through its built-in
SimpleToken authentication mechanism. Any third party SSO integration must
therefore be setup to coexist properly with IBM Cloud Orchestrator REST APIs.
Many SSO modules including Kerberos integration therefore support to limit the
application of the SSO interception to certain URI paths. Ensure that only the
following paths are used for SSO:
v ProcessCenter
v Process Admin
v portal
v login

Configuring the logout redirect URL

By default, IBM Cloud Orchestrator redirects to the login page after a successful
logout. In an SSO context, it may be desirable to redirect to another page instead.
The other page can perform a log out of the SSO context. Some customers also
prefer to redirect to a company home page or tools launch page.
IBM Cloud Orchestrator supports configuring the logout redirect URL through its
customization properties file. To do that, set the logout URL as logoutUrl in the
customizations.json metadata properties. The logout URL must be an absolute
URL like http://www.ibm.com.
For more information about configuring the customizations.json file, see
Metadata file properties in customization file on page 246.

Setting NTP servers

Use Network Time Protocol (NTP) servers to maintain a synchronized time and
date across your systems and virtual machines.

About this task

A configured NTP server that is accessible by your virtual machines is required to
successfully deploy a virtual application pattern or virtual system pattern. When
virtual application patterns or virtual system patterns are deployed, the NTP
server is used to establish the system time for your virtual machines. Without a
synchronized date and time, problems might occur resulting in incomplete
deployments or failure to start virtual application instances or virtual system
instances. If an NTP server is not used, the system clocks for the IBM Cloud
Orchestrator environment and the hypervisors must be synchronized manually.

Procedure
1. On the system where the Workload Deployer component is installed, edit the
/opt/ibm/rainmaker/purescale.app/private/expanded/ibm/scp.ui-1.0.0/
config/openstack.config file.
2. In the /config/openstack section, set the NTP servers as shown in the
following example:

Chapter 2. Installing

83

"ntp_servers": [
dsnode.customer.ibm.com,
"127.0.0.1",
"127.0.0.2",
"127.0.0.3"
]

Note:
a. The list of the defined NTP servers is propagated to the provisioned virtual
machines, and is used to configure NTP on the virtual machines.
b. The list must include at least one valid NTP server for each region.
c. A maximum of four entries are used. IP addresses or FQDNs are allowed.
d. By default, the list contains only the NTP servers that are configured in the
/etc/ntp.conf file on the system where the Workload Deployer component
is installed.
e. During IBM Cloud Orchestrator installation, only one NTP server is
configured: that is, the Deployment Service node.
3. Restart the Workload Deployer service by running the following command:
service iwd restart

Results
After completing these steps, you have defined an NTP server to maintain clock
synchronization across your environments.

Move the database to an external system

If the current DB2 installation is not able to meet with adequate performance the
increasing workload, you can set up a more powerful machine where to move the
database.

Before you begin

Be sure that you specified a service IP address when you registered the DB2 node.
For more information, see Registering the nodes on page 199.

Procedure
1. Shut down IBM Cloud Orchestrator.
2. Back up the database on the DB2 node.
3.
4.
5.
6.
7.

Remove the service IP address from the DB2 node.

Configure the service IP address to the new machine.
Set up DB2 on a new machine.
Restore the database back to new DB2.
Start the new DB2 server.

8. Start IBM Cloud Orchestrator.

84

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Configuring Central Nodes to connect to deployed virtual

machines
When you apply VlanManager as your network configuration and the deployed
virtual machines are all in some virtual LANs, then the Central Nodes must be
configured to manually connect to these deployed virtual machines.

Procedure
1. Check whether your network is VlanManager:
[root@ico24-node2 ~]# nova network-list
+--------------------------------------+------------+----------------+
| ID
| Label
| Cidr
|
+--------------------------------------+------------+----------------+
| e45ffdd5-0f97-482b-80ff-16058a980f8a | VM Network | 192.0.2.0/22
|
+--------------------------------------+------------+----------------+
[root@ico24-node2 ~]# nova network-show e45ffdd5-0f97-482b-80ff-16058a980f8a
+---------------------+--------------------------------------+
| Property
| Value
|
+---------------------+--------------------------------------+
| bridge
| br4096
|
| bridge_interface
| eth1
|
| broadcast
| 192.0.2.255
|
| cidr
| 192.0.2.0/22
|
| cidr_v6
| |
| created_at
| 2014-07-16T02:32:59.568911
|
| deleted
| 0
|
| deleted_at
| |
| dhcp_start
| 192.0.2.2
|
| dns1
| 8.8.4.4
|
| dns2
| |
| gateway
| 192.0.2.1
|
| gateway_v6
| |
| host
| |
| id
| e45ffdd5-0f97-482b-80ff-16058a980f8a |
| injected
| True
|
| label
| VM Network
|
| multi_host
| False
|
| netmask
| 255.255.252.0
|
| netmask_v6
| |
| priority
| |
| project_id
| |
| rxtx_base
| |
| updated_at
| 2014-07-16T02:35:00.931734
|
| vlan
| 100
|
| vpn_private_address | |
| vpn_public_address | |
| vpn_public_port
| |
+---------------------+--------------------------------------+

As above if its property "vlan" has a value then this network is in the type of
vlan.
2. Configure your Central nodes networks:
Take network in step 1 as an example. Virtual machines deployed to this
network have IP addresses in range 192.0.2.0/22 and in the VLAN 100. Then
you should set your Central Nodes networks to connect to these IP addresses
in the VLAN 100.
a. Add a vlan device in your Central Nodes:

Chapter 2. Installing

85

[root@ico24-node2 ~]# vconfig add eth1 100

Added VLAN with VID == 100 to IF -:eth1:[root@ico24-node2 ~]# ip link
1: lo: <LOOPBACK,UP,LOWER_UP&gt; mtu 16436 qdisc noqueue state UNKNOWN
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP&gt; mtu 1500 qdisc mq state UP qlen 1000
link/ether 00:50:56:93:4c:8e brd ff:ff:ff:ff:ff:ff
8: eth1.100@eth1: <BROADCAST,MULTICAST&gt; mtu 1500 qdisc noop state DOWN
link/ether 00:50:56:93:4c:8e brd ff:ff:ff:ff:ff:ff</b></p>

As above, device 8 is the created device.

b. Enable your created device:
[root@ico24-node2 ~]# ifconfig eth1.100 up
[root@ico24-node2 ~]# ifconfig
eth1

Link encap:Ethernet HWaddr 00:50:56:93:4C:8E

inet addr:192.0.2.225 Bcast:192.0.2.255 Mask:255.255.252.0
inet6 addr: fe80::250:56ff:fe93:4c8e/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:14879888 errors:0 dropped:0 overruns:0 frame:0
TX packets:7014089 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:28035905536 (26.1 GiB) TX bytes:9284891183 (8.6 GiB)

eth1.100

Link encap:Ethernet HWaddr 00:50:56:93:4C:8E

inet6 addr: fe80::250:56ff:fe93:4c8e/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 b) TX bytes:468 (468.0 b)

lo

Link encap:Local Loopback

inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:16436 Metric:1
RX packets:67398644 errors:0 dropped:0 overruns:0 frame:0
TX packets:67398644 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:42055289407 (39.1 GiB) TX bytes:42055289407 (39.1 GiB)

c. Add a virtual bridge:

[root@ico24-node2 ~]# brctl addbr br100
[root@ico24-node2 ~]# brctl addif br100 eth1.100
[root@ico24-node2 ~]# brctl show
bridge name
br100

bridge id
8000.005056934c8e

STP enabled
no

interfaces
eth1.100

As above create a virtual bridge and enslave the created device to it.
d. Add address to bridge:
Find an available IP in the 192.0.2.0/22 and assign it to the bridge:
[root@ico24-node2 ~]# ifconfig br100 192.0.2.192 netmask 255.255.252.0
[root@ico24-node2 ~]# ifconfig br100 up

86

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: After step 2, you can find a an available IP in the 192.0.2.0/22 and
assign it to the eth1.100 directly. After all steps finished, you should
configure your route.
Note: Reserve the IP address in your OpenStack environment to avoid
conflicts.

OpenStack configuration
Configure various OpenStack components that are used by IBM Cloud
Orchestrator.

Configuring OpenStack to support resource overcommitment

IBM Cloud Orchestrator supports memory and CPU overcommitment for VMware
and KVM regions.

About this task

In the /etc/nova/nova.conf file on the region server, use the cpu_allocation_ratio
configuration option to specify the virtual CPU to physical CPU allocation ratio,
and use the ram_allocation_ratio configuration option to specify the virtual RAM
to physical RAM allocation ratio.
After you change the /etc/nova/nova.conf file, you must restart the nova services.

Deploying multiple Cinder nodes as Storage Nodes

You can deploy multiple Cinder nodes as Storage Nodes by customizing the
Deployment Topology Templates.

Procedure
1. Setup a Cinder volume service on the existing nodes, take the KVM Compute
Node for example:
Modify the chef-runlist by adding two roles role[os-block-storagescheduler],role[os-block-storage-volume], like in the following sample, then
update templates and jobs. In this example, all the KVM Compute Nodes in the
cloud deployment have a Cinder volume service enabled:
"kvm_compute": {
"Type": "IBM::SCO::Node",
"Properties": {
"Address": "COMPUTE_ADDR",
"User": "root",
"Password": "passw0rd",
"KeyFile": "/home/heat/.ssh/heat_key"
},
"Metadata": {
"chef-runlist": "role[kvm-compute],role[os-block-storage-scheduler],role[os-block-storage-volume]",
"order": 3,
"multiple": true
}
}

2. Setup a Cinder volume service on the new nodes:

Define new resource name in template files, modify chef-runlist of the
resource name by adding role[os-block-storage-scheduler],role[os-blockstorage-volume]. After the nodes are deployed with the newly-defined resource
name, the Cinder volume service is enabled.

Chapter 2. Installing

87

Managing Nova networks

IBM Cloud Orchestrator uses VLAN network that is also compatible with flat
interface. You can add additional networks in addition to the network created
during the IBM Cloud Orchestrator installation procedure.
Adding a network for a KVM Region:
There are two types of network for a KVM Region.
Before you begin
v Ensure your environment meets all the requirements described in Planning
networks on page 24.
v Identify all the IP addresses that are already in use in the IP range that you plan
to use. You must mark these IP addresses as reserved in OpenStack so that IP
conflicts do not occur at deployment time. To reserve IP addresses, use the nova
fixed-ip-reserve <fixed_IP> command.
v All the Compute Nodes must use the same interface to connect to the Region
Server. For example, eth0, eth1, or eth2.
Procedure
1. To create a vlan network for vlan interface, run the following command on one
line on the Region Server:
nova-manage network create --label=LABEL
--fixed_range_v4=X.X.X.X/YY --num_networks=1
--network_size=256 --gateway=GATEWAY_IP
--vlan=VLAN --bridge_interface=NIC
--dns1 X.X.X.X --dns2 X.X.X.X --project PROJECT_ID

For example:
nova-manage network create --label=VLAN106
--fixed_range_v4=10.10.6.0/24 --num_networks=1 --network_size=256
--gateway=10.10.6.1 --vlan=106 --bridge_interface=eth3
--dns1 9.110.51.41 --dns2 9.110.51.41 --project 9d9d88a46e5b4022aef64f6b2ed42469

The bridge_interface parameter is the interface that all compute nodes

configured to the VLAN in their switch. After the VLAN network is created, no
new VLAN or bridge device is created in the compute node until a virtual
machine is deployed in the compute node.
The project parameter associates the specified PROJECT_ID with the network, so
that only the users assigned to that project can access the network. You can
associate only one project with a network.
2. To create a vlan network for flat interface:
a. Create a bridge on each compute node. Select any number from 0 to 4095,
for example, 4080:
brctl addbr br4080

Edit /etc/sysconfig/network-scripts/ifcfg-br4080 with the following

content:
DEVICE=br4080
TYPE="Bridge"
BOOTPROTO="none"
DELAY=0
ONBOOT=yes

Then run this command:

ifup br4080

88

IBM Cloud Orchestrator 2.4.0.2: User's Guide

b. Enslave the flat interface, for example eth3, to the bridge created in step 1.
Note: This interface must be different than the value of
managment_network_device in the region-server.cfg file. And all the KVM
compute nodes must be in use.
Run:
brctl addif br4080 eth3

Note: Make sure there is no IP address on this flat interface. You can ensure
this with command ifconfig eth3 0.0.0.0 up.
Add BRIDGE=br4080 in the /etc/sysconfig/network-scripts/ifcfg-eth3 file
as in the following example:
DEVICE="eth3"
BOOTPROTO=none
NM_CONTROLLED="yes"
ONBOOT=yes
TYPE="Ethernet"
BRIDGE=br4080

c. Create a fake VLAN interface and enslave it by running the following

commands:
tunctl -t vlan4080
brctl addif br4080 vlan4080

Important: Complete Steps 1 to 3 on the Region Server and each of the

compute nodes.
d. Run the following command on one line to create a network on the Region
Server:
nova-manage network create --label=<newnet>
--fixed_range_v4=X.X.X.X/YY --num_networks=1
--network_size=256 --gateway=<NEWNET_GW>
--vlan=4080 --bridge=br4080 --bridge_interface=eth3
--dns1 X.X.X.X --dns2 X.X.X.X

For example:
nova-manage network create --label=flat-network
--fixed_range_v4=10.10.11.0/24 --num_networks=1
--network_size=256 --gateway=10.10.11.1 --vlan=4080
--bridge=br4080 --bridge_interface=eth3
--dns1 9.110.51.41 --dns2 9.110.51.41

e. If there is an existing DHCP service running on this flat network, run the
following command on all compute nodes including on the Region Server:
ebtables -t nat -A POSTROUTING -o $flat_interface -p IPv4 --ip-protocol udp
--ip-destination-port 67 -j DROP

Where $flat_interface is the flat interface you are going to make use of.
3. (Optional) If you want users from multiple projects to access the same network,
you must disassociate all projects from the network, which sets the project_id
value for the network to None. To disassociate all projects from the network, run
the following command on the Region Server:
nova-manage network modify X.X.X.X/YY -disassociate-project

For example:
nova-manage network modify 10.10.6.0/24 -disassociate-project

4. Configure the nodes to use the new gateway. Otherwise, they might use their
host as a gateway. Run the following commands on the Region Server and on
each compute node:
Chapter 2. Installing

89

echo "dhcp-option=tag:LABEL,option:router,GATEWAY_IP" >>

/etc/dnsmasq.d/nova.gateway
echo "domain=DNS_SUFFIX,X.X.X.X/YY" >>
/etc/dnsmasq.d/nova.domain

5. Stop all dnsmasq services and restart the openstack-nova-network service on the
Region Server or compute node:
killall dnsmasq
service openstack-nova-network restart

Adding a network for a VMware Region:

This topic describes how you add a network for a VMware Region.
Before you begin
v Ensure your environment meets all the requirements described in Planning
networks on page 24.
v Identify all the IP addresses that are already in use in the IP range that you plan
to use. You must mark these IP addresses as reserved in OpenStack so that IP
conflicts do not occur at deployment time. To reserve IP addresses, use the nova
fixed-ip-reserve <fixed_IP> command.
v The port groups must exist in VMware and at network creation time you must
specify its exact name as the label.
Procedure
1. To create a network, run the following command on one line on the Region
Server:
nova-manage network create --label=LABEL
--fixed_range_v4=X.X.X.X/YY --num_networks=1
--network_size=256 --gateway=GATEWAY_IP
--vlan=VLAN --bridge_interface=NIC
--dns1 X.X.X.X --dns2 X.X.X.X --project PROJECT_ID

For example:
nova-manage network create --label=VLAN106
--fixed_range_v4=10.10.6.0/24 --num_networks=1 --network_size=256
--gateway=10.10.6.1 --vlan=106 --bridge_interface=eth3
--dns1 9.110.51.41 --dns2 9.110.51.41 --project 9d9d88a46e5b4022aef64f6b2ed42469

The label parameter must the same with the name of port group that you
want to create network for, the vlan parameter is the vlan ID that you
configured in the port group. If no vlan assigned to the port group, please
specify any Vlan ID, and add attribute, ignore_vswitch_validation, under the
[vmware] section in Nova. The project parameter associates the specified
PROJECT_ID with the network, so that only the users assigned to that project can
access the network. You can associate only one project with a network.
2. (Optional) If you want users from multiple projects to access the same network,
you must disassociate all projects from the network, which sets the project_id
value for the network to None. To disassociate all projects from the network, run
the following command on the Region Server:
nova-manage network modify X.X.X.X/YY --disassociate-project

For example:
nova-manage network modify 10.10.6.0/24 --disassociate-project

90

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Results
The network can now be accessed by all users in all projects.
Deleting the existing networks:
This topic describes the commands that can be used to disassociate the project
from the network, delete an existing network, or delete the virtual machines that
belong to it.
Procedure
1. To delete all virtual machines in the network through GUI or CLI, run:
nova delete xxxx

.
2. To disassociate the project from the network, run:
nova-manage network modify x.x.x.x/yy --disassociate-project

.
3. To delete a network, run:
nova-manage network delete x.x.x.x/yy

.
4. If the network that you want to delete is not a network created in the
out-of-box installation, delete the related bridges and the dnsmasq service on the
Region Server and each of the compute nodes. Run the following commands:
ifconfig brxxxx down
brctl delbr brxxxx
killall dnsmasq
/etc/init.d/openstack-nova-network restart

Associating a Nova network to a project:

To achieve network segregation, it is important that you associate each network to
a specific project ID. This is mandatory for KVM regions.
About this task
In KVM regions, VLANManager is the network manager for VLAN-based
networks and for flat networks. VLANManager is designed to deploy the
virtual-machine instances of different projects in different subnets. Therefore, in a
KVM region, flat networks and VLAN networks must be associated with a project
before you use the network.
In VMware regions you can use either FlatManager or VLANManager as the
network manager. FlatManager uses one flat IP address pool that is defined
throughout the cluster. This address space is shared among all user instances,
regardless to which project the instance belong. Each project can take any address
that is available in the pool. Therefore, when using FlatManager, you do not need
to associate the network with a project before you use the network.
In VMware regions, FlatManager is the default for environments upgraded from
SmartCloud Orchestrator 2.3, VLANManager is the default for IBM Cloud
Orchestrator environments that do not use Neutron.

Chapter 2. Installing

91

When you associate a network with a project, only the users assigned to that
project can access the network. You can associate a network with only one project.
If you want users from multiple projects to access the same network, you must
disassociate the network from all projects, which sets the project_id value for the
network to None. The network can then be accessed by all users in all projects.
Procedure
1. To view the details of an OpenStack network, run the nova network-show
network_id command on the Region Server as the admin user, as shown in the
following example:
nova network-show e325a701-ab07-4fb9-a7df-621e0eb31c9b
+---------------------+--------------------------------------+
| Property
| Value
|
+---------------------+--------------------------------------+
| bridge
| br4090
|
| bridge_interface
| eth1
|
| broadcast
| 10.10.255.255
|
| cidr
| 10.10.0.0/16
|
| cidr_v6
| None
|
| created_at
| 2013-04-20T09:43:40.000000
|
| deleted
| False
|
| deleted_at
| None
|
| dhcp_start
| 10.10.0.56
|
| dns1
| 10.10.0.57
|
| dns2
| 10.10.0.1
|
| gateway
| 10.10.0.1
|
| gateway_v6
| None
|
| host
| None
|
| id
| e325a701-ab07-4fb9-a7df-621e0eb31c9b |
| injected
| False
|
| label
| public
|
| multi_host
| True
|
| netmask
| 255.255.0.0
|
| netmask_v6
| None
|
| priority
| None
|
| project_id
| 9d9d88a46e5b4022aef64f6b2ed42469
|
| rxtx_base
| None
|
| updated_at
| 2013-04-20T09:44:41.000000
|
| vlan
| 4090
|
| vpn_private_address | 10.10.0.2
|
| vpn_public_address | 127.0.0.1
|
| vpn_public_port
| 1000
|
+---------------------+--------------------------------------+

The project_id value must be set to the ID of the project to which the users
are assigned, or set to None to grant access to this network to all users in all
projects.
2. To associate a project with a network, run the following command on one line
on the Region Server:
nova-manage network modify X.X.X.X/YY --project $PROJECT_ID

where $PROJECT_ID is the project ID of the project that you want to associate
with the network.
For example:
nova-manage network modify 10.10.0.0/16 --project 9d9d88a46e5b4022aef64f6b2ed42469

3. If you want the network to be accessed by users from several projects,

disassociate all projects from the network by running the following command
on the Region Server:

92

IBM Cloud Orchestrator 2.4.0.2: User's Guide

nova-manage network modify X.X.X.X/YY --disassociate-project

For example:
nova-manage network modify 10.10.6.0/24 --disassociate-project

If you want the network to be used by users from several projects, run the
following command to disassociate the project from the network:
nova-manage network modify 10.10.0.0/16 --disassociate-project

To verify that the network is disassociated from the project, run the following
command:
nova network-show e325a701-ab07-4fb9-a7df-621e0eb31c9b
+---------------------+--------------------------------------+
| Property
| Value
|
+---------------------+--------------------------------------+
| bridge
| br4090
|
| bridge_interface
| eth1
|
| broadcast
| 10.10.255.255
|
| cidr
| 10.10.0.0/16
|
| cidr_v6
| None
|
| created_at
| 2013-04-20T09:43:40.000000
|
| deleted
| False
|
| deleted_at
| None
|
| dhcp_start
| 10.10.0.56
|
| dns1
| 10.10.0.57
|
| dns2
| 10.10.0.1
|
| gateway
| 10.10.0.1
|
| gateway_v6
| None
|
| host
| None
|
| id
| e325a701-ab07-4fb9-a7df-621e0eb31c9b |
| injected
| False
|
| label
| public
|
| multi_host
| True
|
| netmask
| 255.255.0.0
|
| netmask_v6
| None
|
| priority
| None
|
| project_id
| None
|
| rxtx_base
| None
|
| updated_at
| 2013-04-20T15:09:35.000000
|
| vlan
| 4090
|
| vpn_private_address | 10.10.0.2
|
| vpn_public_address | 127.0.0.1
|
| vpn_public_port
| 1000
|
+---------------------+--------------------------------------+

The project_id value is set to None, which means that the network is shared
and can be accessed by all users in all projects.

Managing Neutron networks

Manage a Neutron network in your IBM Cloud Orchestrator environment.

Chapter 2. Installing

93

Adding Neutron networks:

You can add a Neutron network to your IBM Cloud Orchestrator environment.
For information about how to define a Neutron network, see Creating a network
on page 272 and Adding a subnet to an existing network on page 274.
You can assign the network to a specific project and you can select one of the
following provider network types:
FLAT

All instances reside on the same network, which can also be shared with
the hosts. No VLAN tagging or other network segregation takes place. It
does not support overlapping IP addresses.

Local

Instances reside on the local compute host and are effectively isolated from
any external networks.

VLAN Networking allows users to create multiple provider or tenant networks

using VLAN IDs (802.1Q tagged) that correspond to VLANs present in the
physical network. This allows instances to communicate with each other
across the environment. They can also communicate with dedicated
servers, firewalls, load balancers and other networking infrastructure on
the same layer 2 VLAN. It does not support overlapping IP addresses.
VXLAN
VXLAN use network overlays to support private communication between
instances. A Networking router is required to enable traffic to traverse
outside of the VXLAN tenant network. A router is also required to connect
directly-connected tenant networks with external networks, including the
Internet. The router provides the ability to connect to instances directly
from an external network using floating IP addresses.
You must use OpenStack command line to create VXLAN networks as described in
the following topics. For information about the Neutron scenarios, see Neutron
scenarios on page 27.
Scenario 1: Use network server as gateway:
This topic describes how you use a network server as a gateway.
About this task
The following procedure refers to the command line commands. You can perform
the same action from the Administration user interface.
Procedure
1. Create a network to access public network (internet):
Check the value of physical_interface_mappings in the configuration file -/etc/neutron/plugins/linuxbridge/linuxbridge_conf.ini on the network
server; it may be one of the following configurations depending on the
deployment topology:
Note: All neutron commands must be run on the Region node.
a. physical_interface_mappings = physnet1:eth0:
This means that the management_interface, data_interface,
external_interface all use the same NIC -- eth0, so the network creation
command is:

94

IBM Cloud Orchestrator 2.4.0.2: User's Guide

neutron net-create <public_net_name> --router:external=True

--provider:network_type flat --provider:physical_network physnet1

b. physical_interface_mappings = physnet1:eth0,physnet2:eth1:
This means that management_interface and external_interface use the
same NIC -- eth0, and data_interface uses eth1, so the network creation
command is:
neutron net-create <public_net_name> --router:external=True
--provider:network_type flat --provider:physical_network physnet1

c. physical_interface_mappings =
physnet1:eth0,physnet2:eth1,physnet3:eth2:
This means that management_interface uses eth0, data_interface uses eth1
and external_interface uses eth2, so the network creation command is:
neutron net-create <public_net_name> --router:external=True
--provider:network_type flat --provider:physical_network physnet3

Note: If network you are going to access the public network (internet) is
using a VLAN, for example 1000, then the command becomes:
neutron net-create public --router:external=True --provider:network_type vlan
--provider:physical_network physnetX --provider:segmentation_id 1000

physnetX is what external_interface maps to, and it is physnet1 in most

cases.
After the layer 2 network is created, one or more subnetworks can be added
into it with the following command:
neutron subnet-create --gateway 192.0.2.1 public 192.0.2.0/24
--allocation-pool start=192.0.2.100,end=192.0.2.200 --name sub-pub

Note: This also means the floating IP pool.

2. Create networks for virtual machines:
For KVM, it can be either VLAN or VXLAN, while for VMware only VLAN is
supported. If using VLAN, you must ensure the trunks in switch are
configured properly:
neutron net-create <vlan_net_name> --tenant-id <tenant_id> --provider:network_type vlan
--provider:physical_network <physnetX> --provider:segmentation_id <number>

or:
neutron net-create <vxlan_net_name> --tenant-id <tenant_id> --provider:network_type vxlan
--provider:segmentation_id <number>

For VMware, since a VMware native driver does not support to create the port
group in vCenter automatically, you must create the corresponding port group
in vCenter for each created network by manually before boot the virtual
machine, the name of port group must be the same as the name (label) of the
neutron networks.
Note: For VLAN, the trunked port must be configured properly for the
<number> and <physnetX> must be data_interface. For VXLAN, <number> must
be from 1000 to 160000.
Add subnetworks into it which means reserve IP ranges for the virtual
machines, for example:
neutron subnet-create <vlan_net_name | vxlan_net_name>10.10.10.0/24

3. Create routers for virtual machines:

Create a router:
Chapter 2. Installing

95

neutron router-create router1

Make the router able to access public network:

neutron router-gateway-set router1 <public network uuid>

Note: <public network uuid> is the one created in 1 on page 94.

Make virtual machines network connect to the router:
neutron router-interface-add router1 <subnet uuid>

Note: <subnet uuid> is the subnet in 2 on page 95 created by subnet-create

command.
Scenario 2: Use a physical gateway:
This topic describes how to use a physical gateway.
About this task
The following procedure refers to the command line commands. You can perform
the same action from the Administration user interface.
Procedure
Create networks for virtual machines:
neutron net-create <vlan_net_name> --tenant-id <tenant_id> --provider:network_type vlan
--provider:physical_network <physnetX> --provider:segmentation_id <number>

or:
neutron net-create <flat_net_name> --tenant-id <tenant_id> --provider:network_type flat

For VLAN, the trunked port must be configured properly for the <number> and
<physnetX> must be data_interface:
neutron subnet-create <vlan_net_name | vxlan_net_name> 10.10.10.0/24
--gateway <gateway_IP_on_router>

Restriction: For KVM, VMware, or Hyper-V, only Flat and VLAN mode can be
used. VXLAN, overlapping IP and floating IP are not supported for this scenario.
For information about z/VM network scenarios, see the Enabling z/VM for
OpenStack (Support for OpenStack Icehouse Release) guide at http://
www.vm.ibm.com/sysman/openstk.html.
Scenario 3: Hybrid SDN and physical routing:
This topic describes a hybrid configuration for scenario 1 and 2.
It means you may have different types of networks together. Take the following
scenario as an example:
v Network 1: VXLAN, it must use network server as gateway (configure with
Scenario 1: Use network server as gateway on page 94).
v Network 2: VLAN, you want that virtual machines on it can be accessed directly
through physical routing so this network uses physical gateway (configure with
Scenario 2: Use a physical gateway).
v Network 3 and network 4: one is VLAN and another is VXLAN, but they use
the same network CIDR (meaning overlapping IP range), to support this, you

96

IBM Cloud Orchestrator 2.4.0.2: User's Guide

must use the network server as gateway (configure with Scenario 1: Use
network server as gateway on page 94).
v Network 5: you want to use floating IP to access the virtual machines on it, then
you must use the network server as gateway (configure with Scenario 1: Use
network server as gateway on page 94).
Note: If mgmt_interface = data_interface = external_interface, see
Customizing deployment parameters on page 37 for information about these
interfaces. If you are going to have both Flat and VXLAN networks, you must
ensure that:
1. Flat networks must be created first.
2. Before any virtual machines boot on it, you must first manually create a bridge
(same as the network server) on each Compute Node.
Associating a Neutron network to a project:
To achieve network segregation, it is important that you associate each network to
a specific project ID by using the Administration user interface.
You can assign a network to a project at network creation time. You cannot
reassign a network to a different project after network creation.
Creating multiple networks assigned to different projects:
Create Neutron networks that are mapped to different VLANs, and assign the
networks to different projects.
Before you begin
Create Project A and Project B in the same domain, as described in Creating a
project on page 265. Create User A assigned to Project A, and User B assigned to
Project B, as described in Creating a user on page 272. Assign the admin role to
the Cloud Administrator. Assign the member role to User A and User B.
About this task
You create two networks and assign them to Project A: Network A1 uses VLAN
101, and Network A2 uses VLAN 102. Similarly, you create two other networks
and assign them to Project B: Network B1 uses VLAN 201, and Network B1 uses
VLAN 202.
You then log in as User A in Project A, and deploy virtual machines to connect to
Network A1 and Network A2. Similarly, you log in as User B in Project B, and
deploy virtual machines to connect to Network B1 and Network B2.
Procedure
1. Log in to the Administration user interface as a Cloud Administrator.
2. In the left navigation pane, click ADMIN > System Panel > Networks. The
Networks page is displayed.
3. Create Network A1:
a. Click Create Network. The Create Network window opens.

Chapter 2. Installing

97

Note: The Create Network action in the Administration user interface is

limited to Neutron networks only. To create a Nova network, use the
Self-service user interface.
b. Specify the network name. Example: Network A1.
Note: For VMware, a port group of the same name must exist in vCenter
before deploying any instance.
c. Select a project from the list to assign the network to that project. Example:
Project A
Restriction: You cannot reassign a network to a different project after
network creation.
d. Select the network type from the list. Example: VLAN
e. Specify the other network details.
Name For example testNetwork. If it is a VMware region, there must be a
port group with the same name.
Physical Network
For example physnet1. For information about physnetX, see
Scenario 1: Use network server as gateway on page 94.
Segmentation ID
For example 101. Must be a valid VLAN ID and must have been
configured on the switch correctly.
f. Click Create Network.
The Create Network window closes. The network is created, and the name is
displayed on the Networks page.
4. Create a subnet for Network A1:
a. Click the network name to display the Network Detail page.
b. Click Create Subnet. The Create Subnet window opens.
c. In the Subnet tab, specify the subnet name and other details:
Subnet Name
Any preferred name, for example testSubnet.
Network Address
A planned network CIDR such as 10.10.10.0/24.
Gateway IP
The gateway for this subnet. You can also input the allocation pool
if necessary.
Click Next.
d. In the Subnet Details tab, specify more subnet attributes.
e. Click Create.
The Create Subnet window closes. The subnet is created.
5. Repeat step 3 and step 4 as necessary to create Network A2, Network B1,
Network B2, and the associated subnets.
6. Log in to the Self-service user interface as User A.
7. Deploy a virtual machine to connect to Network A1:
a. Click SELF-SERVICE CATALOG.
b. Click Manage Virtual Machines > Deploy Single Virtual Machine.
c. Specify that the server connects to Network A1.

98

IBM Cloud Orchestrator 2.4.0.2: User's Guide

d. Click Deploy.
The virtual machine is deployed and connects to Network A1.
8. Repeat step 7 to deploy a virtual machine that connects to Network A2.
9. Log in to the Self-service user interface as User B.
10. Repeat step 7 as necessary to deploy virtual machines that connect to
Network B1 and Network B2.
Results
IBM Cloud Orchestrator ensures that the users in one project cannot access another
project. User A can deploy virtual machines that connect only to Network A1 or
Network A2. User B can deploy virtual machines that connect only to Network B1
or Network B2.
You can repeat the steps in this procedure to create additional projects and
networks.
Neutron quota configuration:
You must update the Neutron quota configuration on each network node to
accommodate the intended usage pattern. The default values might not be
sufficient for clouds with more than 50 virtual machines.
On the Neutron node, edit the quota section of /etc./neutron/neutron.conf and
restart the Neutron service.
[QUOTAS]
# resource name(s) that are supported in quota features
quota_items = network,subnet,port
# default number of resource allowed per tenant, minus for unlimited
default_quota = -1
# number of networks allowed per tenant, and minus means unlimited
quota_network = 10
# number of subnets allowed per tenant, and minus means unlimited
quota_subnet = 10
# number of ports allowed per tenant, and minus means unlimited
quota_port = 50
# number of security groups allowed per tenant, and minus means unlimited
quota_security_group = 10
# number of security group rules allowed per tenant, and minus means unlimited
quota_security_group_rule = 100
# default driver to use for quota checks
quota_driver = neutron.db.quota_db.DbQuotaDriver

Chapter 2. Installing

99

Managing flavors
To create a flavor, you can either use the Administration user interface, or run the
nova flavor-create command from the OpenStack Nova compute node on the
appropriate Region Server.
When you create a flavor, ensure that the memory, CPU, and disk values of the
flavor are larger or equal to the values required by the image. To identify the
image requirements, complete the following steps:
1. Log in to the Administration user interface as a Cloud Administrator.
2. In the navigation pane on the left, click ADMIN > System Panel > Images.
3. On the Images page, click an image name to view the image details.
Note: The disk size of the flavor must be larger than the sum of the sizes of all the
disks when you are trying to boot an instance with an existing template. If the disk
size is 0, the instance is booted without a size check.
For z/VM, the disk size is 5 GB. Configure flavors for the supported disk size only.
To make a disk size larger than 5 GB, follow the steps documented in OpenStack
Enablement for z/VM.
To manage flavors for SoftLayer, Amazon EC2 and non-IBM supplied OpenStack,
see Configuring flavors on page 688.
Note: Each Region defines its own distinct set of flavors.
Creating a flavor from the user interface:
To create a flavor, you can use the Administration user interface.
About this task
Remember: When you create a flavor, ensure that you meet the flavor
requirements as described in Managing flavors.
Procedure
1.
2.
3.
4.
5.

Log in to the Administration user interface as a Cloud Administrator.

In the navigation pane on the left, click ADMIN > System Panel > Flavors.
On the Flavors page, click Create Flavor.
On the Flavor Info tab, specify the flavor details.
On the Flavor Access tab, specify the projects that can access the flavor.

6. Click Create Flavor.

Results
The new flavor is listed on the Flavors page.

100

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Creating a flavor from the command line:

To create a flavor, you can run the nova flavor-create command from the
OpenStack Nova compute node on the appropriate Region Server.
Remember: When you create a flavor, ensure that you meet the flavor
requirements as described in Managing flavors on page 100.
The syntax of the nova flavor-create command is as follows:
nova flavor-create [--ephemeral ephemeral] [--swap swap]
[--rxtx-factor factor] [--is-public is-public]
flavor_name flavor_id ram_size disk_size vcpus

where:
v --ephemeral ephemeral (optional) is the ephemeral space size in GB. The default
value is 0.
v --swap swap (optional) is the swap size in MB. The default value is 0.
v --rxtx-factor factor (optional) is the RX/TX factor. The default is 1.
v --is-public is-public (optional) makes the flavor accessible to the public. The
default value is true.
v flavor_name is the name of the new flavor.
v flavor_id is the unique integer ID for the new flavor.
v ram_size is the memory size in MB.
v disk_size is the disk size in GB.
v vcpus is the number of vCPUs.
Example command:
nova flavor-create 4gb1cpu 12345 4096 0 1

For information about the arguments, run the nova help flavor-create command.
To view the currently defined flavors, use the nova flavor-list command.
Customizing flavors for Power features:
Use PowerVC or OpenStack flavors to manage PowerVM LPAR settings.
Basic Flavors for use with PowerVC can be created from IBM Cloud Orchestrator.
Any flavor created on the PowerVC user interface will be automatically imported
to IBM Cloud Orchestrator with a prefix assigned in /etc/powervc/powervc.conf.
Once flavors have been created on PowerVC and imported automatically into IBM
Cloud Orchestrator no further changes will be registered for this flavor.
Any changes made to PowerVC flavors outside the PowerVC Advanced options
will not be reflected in IBM Cloud Orchestrator, this includes, renaming, changing
items such as Disk, Memory, Processors and deleting the flavor entirely.
PowerVC has an additional flavor functionality known as Advanced Compute
Templates. Rather than just specifying the vCPU, memory, disk and processing
units as you would with a standard PowerVC flavor, the advanced flavor allows
you to select a range for minimum, desired, and maximum values for vCPU,
processing units, and memory, and also allows some processor sharing options.
Chapter 2. Installing

101

Only the advanced options on flavors can be updated and have their changes
recognized by IBM Cloud Orchestrator.
Deploying PowerVC virtual machines using flavors:
When deploying a PowerVC virtual machine using a flavor it is necessary to
choose a flavor with a Disk that is equal or greater in size to the Image Disk.
When the virtual machine is deployed the Disk value that was listed in the flavor
is ignored and the virtual machine will be deployed with a Disk the same size as
that specified in the Image.
This means that when performing a Resize, if you choose a flavor with the Disk
greater than that of the original Image it will attempt a Volume resize; even if the
flavor used has the same Disk size as the flavor used to deploy the virtual
machine.
SSP does not support Volume Resize.
SVC does support one resize (flashcopy operation) at a time. Attempting to
perform more than a single flashcopy operation on the same base image will cause
the resize operation to fail, and put the virtual machine in a Error state which can
be reset in the PowerVC UI.
It is recommended where applicable to resize to a flavor which has the same Disk
size as the original image where possible.

Advanced configuration on a VMware region

You can perform advanced configurations on a VMware region.
Before you configure your VMware region, it is important that you understand
how OpenStack interacts with VMware vCenter.
A VMware cluster can be mapped either to an availability zone in OpenStack, or to
a host aggregate. The recommended choice is to have a cluster mapped to an
availability zone, because this choice reflects the idea of a cluster as an entity with
an optimized placement logic and resource grouping. If your VMware cluster has
high-availability (HA) and Distributed Resource Scheduler (DRS) policies, they
continue to be exploited by VMware itself, because they are transparent to
OpenStack. When you define an availability zone or a host aggregate, you can
decide the datastore, the datastore clusters, and the resource pool that must be
used to store the disk of the images. You can use also regular expressions to easily
point to a set of resources.

102

IBM Cloud Orchestrator 2.4.0.2: User's Guide

For example if you want to allow placement in different datastores for the same
cluster to exploit different hardware characteristics of the datastores, you can create
a single availability zone with multiple host aggregates where each host aggregate
points to a different datastore. For more information about how to achieve this
configuration, see Connecting to different datastores in the same cluster on page
106.
If you want to leverage SDRS, configure your environment by following the
procedure described in Enabling Storage DRS on page 112. This can be done per
availability zone or host aggregate.
Templates and virtual machines are automatically discovered and published in
glance and nova after you installed and configured the region server. For more
information, see Configuring vmware-discovery on page 114 and Configuring
vmware-discovery for multiple vCenters on page 116. In this way you can
immediately manage these templates and virtual machines from the
Administration user interface. You can also view the virtual machines from the
Self-service user interface in the Assigned Resources panel. Even if these instances
were not created by IBM Cloud Orchestrator, you can start, stop, resize them, or
run custom actions by using the Self-service user interface. To use the discovered
templates as images for deployments in IBM Cloud Orchestrator, you must modify
them to meet the prerequisites documented in Chapter 6, Managing virtual
images, on page 331.
If the template was created in thin provisioning mode, all the instances generated
from it are thin provisioned. If you want to speed up the cloning operation of
instances spawn from the same template, you can turn on the OpenStack linked
clone feature. This feature can be set per availability zone or host aggregate and
relies on caching the vmdk in the datastore. For more information about this
feature, see http://docs.openstack.org/icehouse/config-reference/content/
vmware.html. Moreover, you can add disks to the image at deployment time or
after the deployment occurred. Volumes can be thin provisioned or thick
provisioned. For more information, see Configuring OpenStack to support thin
provisioning on page 113.

Chapter 2. Installing

103

Connecting to multiple clusters

When you configure a VMware region, you can connect to multiple clusters
defined in the same vCenter. Each cluster is set as a new availability zone in the
same region.

Before you begin

Be familiar with VMware support in OpenStack by reading the related OpenStack
documentation at http://docs.openstack.org/icehouse/config-reference/content/
vmware.html.

About this task

During the IBM Cloud Orchestrator installation, only one openstack-nova-compute
service is created. Because an openstack-nova-compute service can only connect to
one cluster in OpenStack Icehouse, you must create a new openstack-nova-compute
service to connect your new cluster. The new cluster is set as a new host aggregate
in a new availability zone. In the following procedure, new-cluster-availabilityzone is the name of the new availability zone and new-cluster-host-aggregate is
the name of the new host aggregate.
Note: You could add more cluster_name parameters in the nova.conf file instead
of creating a new host aggregate and a new availability zone, but this results in
having two or more clusters in the same availability zone which is not a good
practice from a virtual machine placement point of view.
Note: If you want to create several new openstack-nova-compute services to
connect to different clusters, you may think to install new services on separate
region servers to better manage your resource workload.

Procedure
1. Create the host aggregate and associate it with a new availability zone by
running the following command:
nova aggregate-create new-cluster-host-aggregate new-cluster-availability-zone

This command also creates a new availability zone named

new-cluster-availability-zone. Now you must create a new
openstack-nova-compute service.
2. Create a copy of the /etc/nova/nova.conf file, for example:
cp /etc/nova/nova.conf /etc/nova/nova-service-new-cluster.conf

Change the file ownership by running the following command:

chown nova:nova /etc/nova/nova-service-new-cluster.conf

3. Modify the /etc/nova/nova-service-new-cluster.conf file to set:

[DEFAULT]
default_availability_zone = new-cluster-availability-zone
default_schedule_zone = new-cluster-availability-zone
storage_availability_zone = new-cluster-availability-zone
host = new-cluster
# Use a host name different from the VMware region server to
# avoid conflict with the first cluster configuration.
[vmware]
host_ip = <your vCenter IP address or host name>
cluster_name = <the name of the new cluster in your vCenter>

4. Create a copy of the /etc/init.d/openstack-nova-compute file, for example:

104

IBM Cloud Orchestrator 2.4.0.2: User's Guide

cp /etc/init.d/openstack-nova-compute /etc/init.d/openstack-nova-compute-new-cluster

Change the file ownership by running the following command:

chown nova:nova /etc/init.d/openstack-nova-compute-new-cluster

5. Modify the suffix and config parameters in the /etc/init.d/openstack-novacompute-new-cluster file to set:
suffix=compute-new-cluster
prog=openstack-nova-$suffix
exec="/usr/bin/nova-compute"
config="/etc/nova/nova-service-new-cluster.conf"
pidfile="/var/run/nova/nova-$suffix.pid"
logfile="/var/log/nova/$suffix.log"
-e /etc/sysconfig/$prog ] && . /etc/sysconfig/$prog
lockfile=/var/lock/subsys/$prog

6. Run the following commands to start the services:

chkconfig openstack-nova-compute-new-cluster on
/etc/init.d/openstack-nova-compute-new-cluster start

7. Add the host that you specified in step 3 for the new compute service to the
host aggregate by running the following command:
nova aggregate-add-host new-cluster-host-aggregate new-cluster
+----+----------------------------+-------------------------------+------------| Id | Name
| Availability Zone
| Hosts
+----+----------------------------+-------------------------------+------------| 2 | new-cluster-host-aggregate | new-cluster-availability-zone | new-cluster
+----+----------------------------+-------------------------------+------------+---------------------------------------------------+
| Metadata
|
+---------------------------------------------------+
| availability_zone=new-cluster-availability-zone |
+---------------------------------------------------+

8. Verify that the new service is up and running. Run the following command to
check if the new availability zone which is named new-cluster-availabilityzone is shown:
nova availability-zone-list
+---------------------------------------------+----------------------------------------+
| Name
| Status
|
+---------------------------------------------+----------------------------------------+
| internal
| available
|
| |- <your-local-host-name>
|
|
| | |- nova-conductor
| enabled :-) 2014-08-07T05:15:44.766879 |
| | |- nova-vmware
| enabled :-) 2014-08-07T05:15:51.017709 |
| | |- nova-consoleauth
| enabled :-) 2014-08-07T05:15:49.413705 |
| | |- nova-cert
| enabled :-) 2014-08-07T05:15:47.481551 |
| | |- nova-scheduler
| enabled :-) 2014-08-07T05:15:47.736521 |
| nova
| available
|
| |- <your-local-host-name>
|
|
| | |- nova-compute
| enabled :-) 2014-08-07T05:15:43.274219 |
| new-cluster-availability-zone
| available
|
| |- new-cluster
|
|
| | |- nova-compute
| enabled :-) 2014-08-07T05:15:44.309888 |
+---------------------------------------------+----------------------------------------+

9. For troubleshooting, see the /var/log/nova/compute-new-cluster.log file.

What to do next
After you configured your VMware region to connect to multiple clusters, you
must run the vmware-discovery process as described in Configuring
Chapter 2. Installing

105

vmware-discovery on page 114.

Connecting to different datastores in the same cluster

You can configure your VMware region to connect to different datastores in the
same cluster.

About this task

During the IBM Cloud Orchestrator installation, only one openstack-nova-compute
service is created. To connect to different set of datastores in the same cluster, you
must create a new openstack-nova-compute service for each set of datastores. The
new connection is set as a new host aggregate for each set of datastores. In the
following procedure, datastore1-host-aggregate and datastore2-host-aggregate
are the names of the new host aggregates.

Procedure
1. Create a host aggregate for each set of datastores that you want to connect by
running the following commands, for example:
nova aggregate-create datastore1-host-aggregate your-cluster-availability-zone
nova aggregate-create datastore2-host-aggregate your-cluster-availability-zone

where your-cluster-availability-zone is the availability zone where the

cluster containing the datastores is.
2. Create a copy of the /etc/nova/nova.conf file for each host aggregate that you
created, for example:
cp /etc/nova/nova.conf /etc/nova/nova-service-datastore1.conf
cp /etc/nova/nova.conf /etc/nova/nova-service-datastore2.conf

Change the ownership of the files by running the following commands:

chown nova:nova /etc/nova/nova-service-datastore1.conf
chown nova:nova /etc/nova/nova-service-datastore2.conf

3. Modify the /etc/nova/nova-service-datastore1.conf and

/etc/nova/nova-service-datastore2.conf files to set:
[DEFAULT]
default_availability_zone = your-cluster-availability-zone
default_schedule_zone = your-cluster-availability-zone
storage_availability_zone = your-cluster-availability-zone
host = <datastore-host>
# Use a host name different from the VMware region server to
# avoid conflict with the first cluster configuration.
[vmware]
host_ip = <your vCenter IP address or host name>
cluster_name = <the name of the cluster that contains the datastores in your vCenter>
scheduler_default_filters = AggregateInstanceExtraSpecsFilter,AvailabilityZoneFilter,
RamFilter,ComputeFilter,CoreFilter,SameHostFilter,DifferentHostFilter
datastore_regex = <regular_expression_to_identify_the_datastores>

where
<datastore-host>
Is a different host name in each configuration file. For example,
datastore1-host and datastore2-host.
scheduler_default_filters
Must be specified on one line without spaces.
datastore_regex
Is a regular expression that you can use to identify the set of

106

IBM Cloud Orchestrator 2.4.0.2: User's Guide

datastores in the cluster to be used during the deployment. If you

want to use a specific datastore, just specify the datastore name.
4. Create two copies of the /etc/init.d/openstack-nova-compute file, for
example:
cp /etc/init.d/openstack-nova-compute /etc/init.d/openstack-nova-compute-datastore1
cp /etc/init.d/openstack-nova-compute /etc/init.d/openstack-nova-compute-datastore2

Change the ownership of the files by running the following commands:

chown nova:nova /etc/init.d/openstack-nova-compute-datastore1
chown nova:nova /etc/init.d/openstack-nova-compute-datastore2

5. Modify the suffix and config parameters:

v In the /etc/init.d/openstack-nova-compute-datastore1 file, set:
suffix=compute-datastore1
prog=openstack-nova-$suffix
exec="/usr/bin/nova-compute"
config="/etc/nova/nova-service-datastore1.conf"
pidfile="/var/run/nova/nova-$suffix.pid"
logfile="/var/log/nova/$suffix.log"
-e /etc/sysconfig/$prog ] && . /etc/sysconfig/$prog
lockfile=/var/lock/subsys/$prog

v In the /etc/init.d/openstack-nova-compute-datastore2 file, set:

suffix=compute-datastore2
prog=openstack-nova-$suffix
exec="/usr/bin/nova-compute"
config="/etc/nova/nova-service-datastore2.conf"
pidfile="/var/run/nova/nova-$suffix.pid"
logfile="/var/log/nova/$suffix.log"
-e /etc/sysconfig/$prog ] && . /etc/sysconfig/$prog
lockfile=/var/lock/subsys/$prog

6. Run the following commands to start the services:

chkconfig openstack-nova-compute-datastore1 on
/etc/init.d/openstack-nova-compute-datastore1 start
chkconfig openstack-nova-compute-datastore2 on
/etc/init.d/openstack-nova-compute-datastore2 start

7. Add the hosts that you specified in the step 3 for the new compute services to
the host aggregates by running the following commands:
nova aggregate-add-host datastore1-host-aggregate datastore1-host
nova aggregate-add-host datastore2-host-aggregate datastore2-host
+----+----------------------------+--------------------------------+---------------| Id | Name
| Availability Zone
| Hosts
+----+----------------------------+--------------------------------+---------------| 3 | datastore1-host-aggregate | your-cluster-availability-zone | datastore1-host
| 4 | datastore2-host-aggregate | your-cluster-availability-zone | datastore2-host
+----+----------------------------+--------------------------------+---------------+-----------------------------------------------------------------------+
| Metadata
|
+-----------------------------------------------------------------------+
| availability_zone=your-cluster-availability-zone
|
| availability_zone=your-cluster-availability-zone
|
+-----------------------------------------------------------------------+

8. Set a metadata to the datastore1-host-aggregate and datastore2-hostaggregate host aggregates that you created in the step 1. For example, run the
following commands:
nova aggregate-set-metadata datastore1-host-aggregate Datastore1=true
nova aggregate-set-metadata datastore2-host-aggregate Datastore2=true
+----+----------------------------+--------------------------------+---------------Chapter 2. Installing

107

| Id | Name
| Availability Zone
| Hosts
+----+----------------------------+--------------------------------+---------------| 3 | datastore1-host-aggregate | your-cluster-availability-zone | datastore1-host
| 4 | datastore2-host-aggregate | your-cluster-availability-zone | datastore2-host
+----+----------------------------+--------------------------------+---------------+-----------------------------------------------------------------------+
| Metadata
|
+-----------------------------------------------------------------------+
| Datastore1=true, availability_zone=your-cluster-availability-zone |
| Datastore2=true, availability_zone=your-cluster-availability-zone |
+-----------------------------------------------------------------------+

9. Create new flavors called flavor-datastore1 and flavor-datastore2 by

running the following commands, for example:
nova-manage flavor create flavor-datastore1 4096 1 40 0 72 0 --is_public true
nova-manage flavor create flavor-datastore2 4096 1 40 0 72 0 --is_public true

10. Create the flavor keys to match the metadata that you set in the aggregates by
running the following commands:
nova flavor-key flavor-datastore1 set Datastore1=true
nova flavor-key flavor-datastore2 set Datastore2=true

11. Run the following commands to restart the service:

chkconfig openstack-nova-compute-datastore1 off
chkconfig openstack-nova-compute-datastore1 on
/etc/init.d/openstack-nova-compute-datastore1 stop
/etc/init.d/openstack-nova-compute-datastore1 start
chkconfig openstack-nova-compute-datastore2 off
chkconfig openstack-nova-compute-datastore2 on
/etc/init.d/openstack-nova-compute-datastore2 stop
/etc/init.d/openstack-nova-compute-datastore2 start

Results
You can use the new flavors that you created to deploy to the set of datastores that
you specified in the configuration files.

Connecting to resource pools

You can configure your VMware region to connect to a resource pool.

About this task

To connect to a VMware resource pool, you must add the following property
under the [vmware] section in the related openstack-nova-compute service
configuration file (by default, /etc/nova/nova.conf), and restart the related
openstack-nova-compute service:
resource_pool = <cluster_name>:<resource_pool_name>

where <cluster_name> is the name of the VMware cluster where the resource pool
is defined. When you specify a cluster name and a resource pool name, the
resource pool under the cluster is the target to deploy the virtual machines.
If you have multiple resource pools in the same cluster, you can connect to a
different resource pool for deployment by creating a new host aggregate with a
procedure similar to Connecting to different datastores in the same cluster on
page 106 and specifying different resource pools with the resource_pool variable
in the new openstack-nova-compute service configuration files.

108

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Connecting to multiple vCenters

When you configure a VMware region, you can connect to multiple vCenters. Each
vCenter is set as a new availability zone in the same region.

About this task

When you configure the multiple nova compute services to connect to multiple
vCenters, you must also configure the VMware discovery to connect to these
vCenters. For more information about configuring VMware discovery, see
Configuring vmware-discovery for multiple vCenters on page 116.
To connect to multiple vCenters, you must run the following procedure to create
new OpenStack services. If you want to create several new services to connect to
different vCenters, you may think to install new services on separate region servers
to better manage your resource workload.

Procedure
1. Create a new nova compute service:
Because one openstack-nova-compute service can only connect to one vCenter
in OpenStack Icehouse, you must create a new openstack-nova-compute service
to connect to your new vCenter. The new vCenter is set as a new host
aggregate in a new availability zone. In the following procedure,
new-vCenter-availability-zone is the name of the new availability zone and
new-vCenter-aggregate-host is the name of the new aggregate host.
Perform the following steps:
a. Create the aggregate host and associate it with the new availability zone by
running the following command:
nova aggregate-create new-vCenter-aggregate-host new-vCenter-availability-zone

b.

Create a copy of the /etc/nova/nova.conf file, for example:

cp /etc/nova/nova.conf /etc/nova/nova-service-new-vCenter.conf

Change the file ownership by running the following command:

chown nova:nova /etc/nova/nova-service-new-vCenter.conf

c. Modify the /etc/nova/nova-service-new-vCenter.conf file to set:

[DEFAULT]
default_availability_zone = new-vCenter-availability-zone
default_schedule_zone = new-vCenter-availability-zone
storage_availability_zone = new-vCenter-availability-zone
host = new-vCenter
# Use a host name different from the VMware region server to
# avoid conflict with the first vCenter configuration.
[vmware]
host_ip = <your new vCenter IP address or host name>
cluster_name = <the cluster name in your vCenter>

d. Create a copy of the /etc/init.d/openstack-nova-compute file, for example:

cp /etc/init.d/openstack-nova-compute /etc/init.d/openstack-nova-compute-new-vCenter

Change the file ownership by running the following command:

chown nova:nova /etc/init.d/openstack-nova-compute-new-vCenter

e. Modify the suffix and config parameters in the /etc/init.d/openstacknova-compute-new-vCenter file to set:
suffix=compute-new-vCenter
prog=openstack-nova-$suffix
exec="/usr/bin/nova-compute"
Chapter 2. Installing

109

config="/etc/nova/nova-service-new-vCenter.conf"
pidfile="/var/run/nova/nova-$suffix.pid"
logfile="/var/log/nova/$suffix.log"
-e /etc/sysconfig/$prog ] && . /etc/sysconfig/$prog
lockfile=/var/lock/subsys/$prog

f. Run the following commands to start the services:

chkconfig openstack-nova-compute-new-vCenter on
/etc/init.d/openstack-nova-compute-new-vCenter start

g. Add the host that you specified in step c for the new compute service to the
aggregate host by running the following command:
nova aggregate-add-host new-vCenter-aggregate-host new-vCenter
+----+----------------------------+-------------------------------+------------| Id | Name
| Availability Zone
| Hosts
+----+----------------------------+-------------------------------+------------| 2 | new-vCenter-aggregate-host | new-vCenter-availability-zone | new-vCenter
+----+----------------------------+-------------------------------+------------+---------------------------------------------------+
| Metadata
|
+---------------------------------------------------+
| availability_zone=new-vCenter-availability-zone |
+---------------------------------------------------+

h. Verify if the new computer service is up and running. Run the following
command to check if the new availability zone which named
<your-availability-zone-name> is shown:
nova availability-zone-list
+---------------------------------------------+----------------------------------------+
| Name
| Status
|
+---------------------------------------------+----------------------------------------+
| internal
| available
|
| |- <your-local-host-name>
|
|
| | |- nova-conductor
| enabled :-) 2014-08-07T05:15:44.766879 |
| | |- nova-vmware
| enabled :-) 2014-08-07T05:15:51.017709 |
| | |- nova-consoleauth
| enabled :-) 2014-08-07T05:15:49.413705 |
| | |- nova-cert
| enabled :-) 2014-08-07T05:15:47.481551 |
| | |- nova-scheduler
| enabled :-) 2014-08-07T05:15:47.736521 |
| nova
| available
|
| |- <your-local-host-name>
|
|
| | |- nova-compute
| enabled :-) 2014-08-07T05:15:43.274219 |
| new-vCenter-availability-zone
| available
|
| |- new-vCenter
|
|
| | |- nova-compute
| enabled :-) 2014-08-07T05:15:44.309888 |
+---------------------------------------------+----------------------------------------+

i. For troubleshooting, see the /var/log/nova/compute-new-vCenter.log file.

2. For Neutron network:
If you are using a Neutron network, you do not need to do any specific
configuration for multiple vCenters. For information about creating Neutron
networks, see Adding Neutron networks on page 94. Ensure that a port is
created manually after running the neutron net-create command.
3. For Nova network:
If you are using a Nova network, run the following procedure to create a new
openstack-nova-network service for each new openstack-nova-compute service.
Perform the following steps:
a. Create a copy of the /etc/init.d/openstack-nova-network file, for
example:
cp /etc/init.d/openstack-nova-network /etc/init.d/openstack-nova-network-new-vCenter

110

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Change the file ownership by running the following command:

chown nova:nova /etc/init.d/openstack-nova-network-new-vCenter

b. Modify the suffix and config parameters in the /etc/init.d/openstacknova-network-new-vCenter file to set:
suffix=network-new-vCenter
prog=openstack-nova-$suffix
config="/etc/nova/nova-service-new-vCenter.conf"
pidfile="/var/run/nova/nova-$suffix.pid"
logfile="/var/log/nova/$suffix.log"
lockfile=/var/lock/subsys/$prog

Note: Ensure that you are using the same nova configuration file as the
related nova compute service that you created in step 1.
c. Run the following commands to start the services:
chkconfig openstack-nova-network-new-vCenter on
/etc/init.d/openstack-nova-network-new-vCenter start

d. Verify if the new network service is up and running. Run the following
command to check if the new network service under the internal
availability zone is shown:
nova availability-zone-list
+--------------------------------------+-----------------------------------------+
| Name
| Status
|
+--------------------------------------+-----------------------------------------+
| internal
| available
|
| |- <your-local-host-name>
|
|
| | |- nova-conductor
| enabled :-) 2014-08-07T05:15:44.766879 |
| | |- nova-vmware
| enabled :-) 2014-08-07T05:15:51.017709 |
| | |- nova-consoleauth
| enabled :-) 2014-08-07T05:15:49.413705 |
| | |- nova-cert
| enabled :-) 2014-08-07T05:15:47.481551 |
| | |- nova-scheduler
| enabled :-) 2014-08-07T05:15:47.736521 |
| |- new-vCenter
|
|
| | |- nova-network
| enabled :-) 2014-08-07T06:36:21.840562 |
| nova
| available
|
| |- <your-local-host-name>
|
|
| | |- nova-compute
| enabled :-) 2014-08-07T05:15:43.274219 |
| new-vCenter-availability-zone
| available
|
| |- new-vCenter
|
|
| | |- nova-compute
| enabled :-) 2014-08-07T05:15:44.309888 |
+--------------------------------------+-----------------------------------------+

e. For troubleshooting, see the /var/log/nova/network-new-vCenter.log file.

4. Add a new cinder volume service:
Because one openstack-cinder-volume service can only connect to one vCenter
in OpenStack Icehouse, you must create a new openstack-cinder-volume
service to connect your new vCenter. Perform the following steps:
a.

Create a copy of the /etc/cinder/cinder.conf file, for example:

cp /etc/cinder/cinder.conf /etc/cinder/cinder-new-vCenter.conf

Change the file ownership by running the following command:

chown cinder:cinder /etc/cinder/cinder-new-vCenter.conf

b. Modify the /etc/cinder/cinder-new-vCenter.conf file to set :

storage_availability_zone = new-vCenter-availability-zone
default_availability_zone = new-vCenter-availability-zone
vmware_volume_folder = new-vCenter-cinder-volumes
# vmware-volume-folder must be different from the first vCenter configuration.
# the default value for the first configuration is cinder-volumes
host = new-vCenter
Chapter 2. Installing

111

vmware_host_ip = <your new vCenter IP address>

vmware_host_username = <your user name to access the new vCenter>
vmware_host_password = <your password to access the new vCenter>

Note: If you run the new openstack-cinder-volume service on a separate

region server, you do not need to change the default value of the
storage_availability_zone, default_schedule_zone, and host parameters.
c. Create a copy of /etc/init.d/openstack-cinder-volume file, for example:
cp /etc/init.d/openstack-cinder-volume /etc/init.d/openstack-cinder-volume-new-vCenter

Change the file ownership by running the following command:

chown nova:nova /etc/init.d/openstack-cinder-volume-new-vCenter

d. Modify the suffix and config parameters in the /etc/init.d/openstackcinder-volume-new-vCenter file to set:
suffix=volume-new-vCenter
prog=openstack-cinder-$suffix
exec="/usr/bin/cinder-volume"
config="/etc/cinder/cinder-new-vCenter.conf"
pidfile="/var/run/cinder/cinder-$suffix.pid"
logfile="/var/log/cinder/$suffix.log"
lockfile=/var/lock/subsys/$prog

e. Run the following commands to start the services:

chkconfig openstack-cinder-volume-new-vCenter on
/etc/init.d/openstack-cinder-volume-new-vCenter start

f. Verify if the new service is up and running. Run the following command to
check if the new availability zone which named 'new-vCenter-availabilityzone is shown:
cinder availability-zone-list

g. Run the following command to check if the new openstack-cinder-volumenew-vCenter service is shown in the service list:
cinder service-list

h. For troubleshooting, see the /var/log/cinder/volume-new-vCenter.log file.

Enabling Storage DRS

You can enable Storage DRS in your VMware region by editing the nova compute
configuration file on the VMware Region Server.
To support VMware Storage DRS, set the following properties in the [vmware]
section in the related openstack-nova-compute service configuration file (by default,
/etc/nova/nova.conf), and restart the related openstack-nova-compute service:
datastore_cluster_name = <datastore cluster name>
use_sdrs = True

where
datastore_cluster_name
Specifies the name of a VMware datastore cluster (StoragePod name). The
default value is None.
use_sdrs
Specifies whether a driver must attempt to call DRS when cloning a virtual
machine template. The default value is False.

112

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: This feature is only supported when you deploy a virtual machine from
template.
You can use the following extra specs of the flavor to override the specified
configuration when you deploy new virtual machines:
vmware:datastore_cluster_name
Set this key to override the datastore_cluster_name parameter specified in
the nova.conf file.
vmware:use_sdrs
Set this key to override the use_sdrs parameter specified in the nova.conf
file.
To set the extra specs for the flavor, use the nova flavor-key command.

Enabling datastore random selection

You can enable the datastore random selection when booting a virtual machine.
To randomly select an available datastore when booting a virtual machine, add the
following parameter in the [vmware] section in the related openstack-nova-compute
service configuration file (by default, /etc/nova/nova.conf), and restart the related
openstack-nova-compute service:
random_datastore = True

The default value is False.

Configuring OpenStack to support thin provisioning

You can configure OpenStack to support thin provisioning.
You cannot choose the provisioning disk type at deployment time. The
provisioning disk type is inherited from the image template:
If the template is created with a thin-provisioned disk, the instances that are
deployed from that template are thin-provisioned.
v If the template is created with a thick-provisioned disk, the instances that are
deployed from that template are thick-provisioned.

By default, volumes are created with thin-provisioning.

Configuring OpenStack to support linked clones

By default IBM Cloud Orchestrator uses linked clones.
During the virtual machine creation process, the ESX hypervisor requires a copy of
the VMDK file to boot up the virtual machine, for images not existing in the VMware
environment and not discovered by IBM Cloud Orchestrator. As a result, the
vCenter OpenStack Compute driver must download the VMDK through HTTP from
the OpenStack Image Service to a data store that is visible to the hypervisor. To
optimize this process, the first time a VMDK file is used, it gets cached in the data
store. Subsequent virtual machines that need the VMDK use the cached version and
do not have to copy the file again from the OpenStack Image Service. Even with a
cached VMDK, there is still a copy operation from the cache location to the
hypervisor file directory in the shared data store. To avoid this copy, boot the
image in linked_clone mode.
To enable this mode, set the following parameter in the Nova configuration file
(default is /etc/nova/nova.conf):
use_linked_clone = True
Chapter 2. Installing

113

Note also that it is possible to override the linked_clone mode on a single image
basis using the vmware_linked_clone property in the OpenStack Image Service.
To change this behavior, you must modify on the Region Server the Nova
configuration file setting use_linked_clone to False.
You must restart the Nova compute services after updating the Nova configuration
file.

Configuring vmware-discovery
The vmware-discovery process discovers existing virtual machines, templates, and
port groups in your VMware environment.

About this task

The vmware-discovery code is installed in a VMware region in IBM Cloud
Orchestrator. The vmware-discovery configuration file is /etc/vmwarediscovery.conf. The vmware-discovery service is nova-discovery.
Note: IBM Cloud Orchestrator does not support the creation of a volume based on
a discovered image in a VMware Region.
To configure vmware-discovery, complete the following procedure.

Procedure
1. Log on to the VMware Region server as a user with root or sudo access.
2. Edit the /etc/vmware-discovery.conf configuration file.
The following table describes the parameters in the /etc/vmwarediscovery.conf file:
Table 10. Parameters in the /etc/vmware-discovery.conf configuration file
Parameter

Definition

allow_instance_deletion

The default value is False. If set to True, the vmware-discovery

process can delete the instances from OpenStack Nova that are
deleted from the vCenter directly.

allow_template_deletion

The default value is False. If set to True, the vmware-discovery

process can delete the templates from OpenStack Glance that are
deleted from the vCenter directly.

auth_url

The Keystone public endpoint. You can find this value in the
/root/openrc file or the /root/keystonerc file.

keystone_version

This value depends on the value of the auth_url parameter. If the

auth_url value ends with /v2.0, keystone_version is v2.0.
Otherwise, keystone_version is v3.

admin_tenant_name

The administration project. The default value is admin.

admin_user

The Cloud Administrator user. The default value is admin.

admin_password

The password of the specified Cloud Administrator user.

discovery_driver

The full class name for the driver for the VMware Discovery
Service (string value). The value is
vmware.nova.driver.virt.vmware.driver.VMwareVCSynchingDriver

discovery_manager

The discovery driver. The value is

vmware.nova.driver.compute.manager.VMwareDiscoveryManager

staging_project_name

114

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The project to which all discovered instances belong.

Table 10. Parameters in the /etc/vmware-discovery.conf configuration file (continued)

Parameter

Definition

staging_user

The user to whom all discovered instances belong.

image_periodic_sync_interval_in_seconds

The image periodic sync interval specified in seconds. This

interval is the time from the end of one successful image periodic
sync operation to the start of the next. The default value is 300.

instance_prefix

The prefix for all discovered instances.

instance_sync_interval

The instance periodic sync interval specified in seconds. The

default value is 20. The minimum value is 10.

image_limit

The maximum number of images to return. The default value is

500. If your OpenStack has more than 500 images, this limit
should be increased to include all images.

image_sync_retry_interval_time_in_seconds

The time in seconds between image sync retry attempts if an error

was encountered during an image sync operation. The default
value is 60.

longrun_loop_interval
longrun_initial_delay

The minimum delay interval and initial delay in seconds for long
run tasks. The default interval value is 7, and the default delay
value is 10.

flavor_prefix

The prefix for all created flavors for the discovered instances.

full_instance_sync_frequency

The number of instance sync intervals between full instance syncs.

At most intervals, only the instances that are known to be out of
sync are synchronized. However, after the number of intervals
specified by this parameter, all instances are synchronized. The
default value is 30.

vm_ignore_list

The virtual machines that should be ignored by the discovery

process.

vmware_default_image_name

The default image for the discovered instances.

physical_network_mappings

The virtual switch in your vCenter.

port_group_filter_list

The port group name that you want to use. If left blank, the
process discovers all port groups.

portgroup_sync_interval

The port group periodic sync interval specified in seconds. The

default value is 300. The minimum value is the value of the
instance_sync_interval parameter.

target_region

The name of the region where the discovered resources are

registered. The default value is the name of the current region.

template_sync_interval

The template periodic sync interval specified in seconds. The

default value is 300. The minimum value is the value of the
instance_sync_interval parameter.

Note: Do not change the default values of the other parameters in the
/etc/vmware-discovery.conf configuration file.
3. Start the vmware-discovery service:
service nova-discovery start

Note: By default, this service applies to the /etc/nova/nova.conf and

/etc/vmware-discovery.conf configuration files. The vCenter information is in
the /etc/nova/nova.conf file. You can assign a different configuration file by
specifying the --config-file your_configuration_file parameter. You can add
this parameter in the /etc/init.d/nova-discovery service script, as described
in Configuring vmware-discovery for multiple vCenters on page 116.
Chapter 2. Installing

115

You can find the discovery log in the /var/log/nova/discovery.log file.

If you want to stop the vmware-discovery service, run the following command:
service nova-discovery stop

Results
The vmware-discovery process is configured and started after installation in the
VMware region. The default value for the staging project and the staging user is
admin. You can now manage the discovered resources as described in Managing
resources on page 311.

Configuring vmware-discovery for multiple vCenters

You can configurevmware-discovery for environments with multiple vCenters.

About this task

For information about connecting to multiple vCenters, see Connecting to
multiple vCenters on page 109.
Restriction: For a VMware region that connects to multiple vCenters, if images
with the same name exist on different vCenters, only one of these images can be
discovered in the VMware region. Use the nova image-show <image-id> command
to find the image location on each vCenter.
Restriction: IBM Cloud Orchestrator supports one VMware region connected to
multiple vCenters, and all the vCenters must be in same network as the VMware
neutron node.

Procedure
1. Create the configuration files for a specific vCenter:
a. Configuration file for the openstack-nova-compute:
By default, the VMware discovery loads the VMware related information
from the /etc/nova/nova.conf file. Because you already connected to the
other vCenter, there is a configuration file for this vCenter VMware
information which is applied by the related openstack-nova-compute
service. By default, it is in the /etc/nova/ directory. For example,
/etc/nova/nova-2.conf.
b. Configuration file for the vmware-discovery:
Copy the /etc/vmware-discovery.conf file and then modify it as the
discovery configuration file for the new vCenter. For example:
cp /etc/vmware-discovery.conf /etc/vmware-discovery-2.conf

Ensure that the vmware-discovery-2.conf file has ownership of nova:nova.

To change the ownership, run the following command:
chown nova:nova /etc/vmware-discovery-2.conf

2. Create the service file for a specific vCenter:

a. Copy the /etc/init.d/nova-discovery file to a new service file:
cp /etc/init.d/nova-discovery /etc/init.d/nova-discovery-2

Ensure that the new service file has ownership of root:root . To change the
ownership, run the following command:
chown root:root /etc/init.d/nova-discovery-2

b. Modify the new service file /etc/init.d/nova-discovery-2 to:

116

IBM Cloud Orchestrator 2.4.0.2: User's Guide

suffix=discovery-new-SERVICE
prog=nova-$suffix
pidfile="/var/run/nova/nova-$suffix.pid"
logfile="/var/log/nova/$suffix.log"
[ -e /etc/sysconfig/$prog ] && . /etc/sysconfig/$prog
lockfile=/var/lock/subsys/$prog

c. Apply the new configuration files:

daemon --user nova --pidfile $pidfile "$exec --logfile $logfile &>/dev/null \
& echo \$! > $pidfile"

to
daemon --user nova --pidfile $pidfile \
"$exec --config-file /etc/vmware-discovery-2.conf \
--config-file /etc/nova/nova-2.conf \
--logfile $logfile &>/dev/null & echo \$! > $pidfile"

3. Start the new service:

/etc/init.d/nova-discovery-2 start
chkconfig nova-discovery-2 on

Increasing shutdown timeout for virtual machines

You can increase the timeout value for a clean shutdown of VMware virtual
machines.
When you stop a VMware virtual machine from the Self-service user interface, by
default the time to wait for an instance to perform a clean shutdown is 60 seconds.
After this time, the virtual machine is forced to power off.
If you want to increase this value, change the shutdown_timeout parameter in the
[DEFAULT] section in the related openstack-nova-compute service configuration file
(by default, /etc/nova/nova.conf), and restart the service.

Port group validation when using nova network

You can validate a port group when using a nova network.
Add attribute, ignore_vswitch_validation, under the [vmware] section in
nova.conf. The default is False. If True, then do not check if the port group and
the vlan interface are associated on the same virtual switch.
Add attribute, ignore_portgroup_create, under the [vmware] section in nova.conf.
The default is False. If True, then do not create the port group when using nova
network.

Opening VNC port on ESXi host to enable the VNC console

access
You can enable the VNC console access.
On the vSphere Client for all the hosts in the cluster, if you want to access the
virtual machine via VNC console through the Administration UI or the command
line, run: nova get-vnc-console XXXXXX xvpnc:
Select the host and then Configuration -> Security Profile -> Firewall -> Edit
-> gdbserver. Select the check box and click OK.
For production, limit the ports to 5900-6000 for security considerations. The port
range depends on how many virtual machines can run on this host. For more
information about the configuration, see the VNC section under Prerequisites and
limitations in:http://docs.openstack.org/icehouse/config-reference/content/
Chapter 2. Installing

117

vmware.html.

Supporting VMware vSphere 5.0

Users of VMware vSphere 5.0 must host their WSDL files locally.
These steps are applicable for vCenter 5.0 or ESXi 5.0. You can either mirror the
WSDL from the vCenter or ESXi server that you want to use, or you can download
the SDK directly from VMware. These workaround steps fix a known issue with
the WSDL that was resolved in later versions. When setting the VMware VCDriver
configuration options, you must include the wsdl_location option. For more
information, see the OpenStack documentation at: http://docs.openstack.org/
trunk/config-reference/content/vmware.html#VMWare_additional_config.

Supporting Cinder volumes in VMware regions

To correctly create and manage block storage volumes, and optimize their
placement in VMware regions, you must define storage policies in vCenter.
For more information, see the OpenStack documentation at http://
docs.openstack.org/trunk/config-reference/content/vmware-vmdk-driver.html.

Managing content packs

IBM Cloud Orchestrator includes content packs that automate several
infrastructure-as-a-service and platform-as-a-service scenarios.

Installing and configuring content packs

A toolkit is provided with each content pack. To make the content pack processes
available in IBM Cloud Orchestrator, import the associated toolkit into Business
Process Manager.
To
1.
2.
3.

install a content pack, complete the following steps:

In the Business Process Manager Designer, click Process Center.
In Toolkits, click Import Toolkit.
In Import Toolkit, click Browse to select the file to import.

Note: The Toolkit file extension is in twx extension format.

4. Click OK.
To configure the content pack processes as a self-service offering, create a new
self-service category and then a new self-service offering specifying the content
pack process you imported. For information about creating self-service categories
and offerings, see Creating a category on page 327 and Creating an offering on
page 326.

Initializing the IaaS toolkit database

Before using the IaaS toolkit, you must initialize the database.
To initialize the IaaS toolkit database, see the IaaS configuration instructions in
Installing and configuring.

118

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Configuring high availability

Configure your IBM Cloud Orchestrator environment to use high-availability
capabilities.
For information about high availability, see Deployment modes on page 12,
Deployment topologies on page 16, and Managing high availability on page
235.
For information about installing the high-availability topology, see Deploying the
High-Availability Distributed topology on page 53.

Configuring the external database server for the high-availability

topology
The external database must be monitored by System Automation Application
Manager because many IBM Cloud Orchestrator processes depend on the external
database.

About this task

The database instance is a key component of IBM Cloud Orchestrator, and should
be installed with high-availability features (for example, DB2 HADR or DB2 with
shared disk). For more information, see Configuring a clustered environment using
DB2 High Availability Instance Configuration Utility (db2haicu) in the IBM DB2
documentation (http://www-01.ibm.com/support/knowledgecenter/
SSEPGG_10.5.0/com.ibm.db2.luw.admin.ha.doc/doc/t0052800.html).
Any high-availability solution should also manage the DB2 nosql service.
The control script provided (db2ctrl) is a sample script and should be adapted to
suit your installation. The DB2 database service is configured in System
Automation Application Manager as an agentless adapter resource. This
configuration enables System Automation Application Manager to connect to a
highly available database through the virtual IP address, and monitor and manage
DB2 automatically on the active node. If the database is configured as highly
available, you must adapt the commands that are used to manage and monitor the
database.
During installation, the saamuser user is created automatically on various IBM
Cloud Orchestrator servers. However, you must manually create the saamuser user
on the external database server. If you have more than one external database
server, create the saamuser user on each server in your database cluster. After you
create the saamuser user, you must manually create the control scripts and
configure sudo to enable System Automation Application Manager to monitor and
manage the external database.
Tip: The example commands in the following procedure are for a UNIX server. If
the operating system of the external database server is not UNIX, replace the
example commands with the equivalent commands.

Procedure
1. Log in to the external database server as a root user.
2. Create the saamuser user:
# useradd -m saamuser

3. Create the password for the saamuser user:

Chapter 2. Installing

119

# passwd saamuser
New password:
Retype new password:

When prompted for the password, enter the password that is used by the
saamuser user on the IBM Cloud Orchestrator servers.
4. Create the /opt/IBM/tsamp/eez/scripts directory:
# mkdir -p /opt/IBM/tsamp/eez/scripts

5. Copy the following files from the System Automation Application Manager
server to the specified directories on the IBM DB2 server:
v Copy /opt/IBM/tsamp/eez/scripts/servicectrl.sh to /opt/IBM/tsamp/eez/
scripts.
v Copy /opt/IBM/tsamp/eez/scripts/db2ctrl to /etc/init.d.
v Copy /opt/IBM/tsamp/eez/scripts/nosqlctrl to /etc/init.d.
6. If necessary, edit the /etc/init.d/db2ctrl and /etc/init.d/nosqlctrl files to
suit your IBM DB2 installation.
7. Ensure that the saamuser user is the owner of the /opt/IBM/tsamp/eez/scripts
directory and its contents:
# # chown -R saamuser:<saamusergroup>

/opt/IBM/tsamp/eez/scripts

8. Add the db2ctrl script as a service:

chkconfig --add db2ctrl; chkconfig db2ctrl off
chkconfig --add nosqlctrl; chkconfig nosqlctrl off

9. Disable any autostart of the IBM DB2 services for the external database.
10. Configure sudo for the saamuser user:
a. Create the /etc/sudoers.d/saam file with the following content:
# sudoers additional file for /etc/sudoers.d/
# IMPORTANT: This file must have no
or . in its name and file permissions
# must be set to 440
# This file is for the IBM System Automation Application Manager ID to call
# the IBM DB2 control script that is provided with IBM Cloud Orchestrator
Defaults:saamuser !requiretty
# scripts found in control script directory
Cmnd_Alias SACTRL = /sbin/service
# allow for root access
saamuser ALL = (root) NOPASSWD: SACTRL

b. Change the file permissions of the new file:

# chmod 440 /etc/sudoers.d/saam

c. Ensure that the /etc/sudoers file contains the following line:

#includedir /etc/sudoers.d

11. If you have more than one external database server, repeat this procedure to
create the saamuser user on each server in your database cluster.

Results
System Automation Application Manager can now use the saamuser user to
monitor the external database.

120

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Enabling autostart of System Automation Application Manager

Because System Automation Application Manager is not started when the virtual
machine where it is installed starts, you must enable autostart of System
Automation Application Manager at startup.
To automatically start System Automation Application Manager at the startup of
the virtual machine where it is installed, complete the following steps:
1. Log on, as a root user, to the virtual machine where System Automation
Application Manager is installed.
2. Create a script named saam.conf in the /etc/init directory, and insert the
following content:
#IBM System Automation Application Manager Startup
description IBM System Automation Application Manager
version SAAM 4.1.0.0
start on stopped rc RUNLEVEL=[345]
stop on starting rc RUNLEVEL=[016]
console output
pre-start script
su db2inst1 -c /home/db2inst1/sqllib/adm/db2start
sleep 10
/opt/IBM/WebSphere/AppServer/bin/startServer.sh server1
sleep 30
eezdmn start
eezaladapter start
end script
post-stop script
eezaladapter stop
eezdmn -SHUTDOWN
/opt/IBM/WebSphere/AppServer/bin/stopServer.sh server1 -username wasadmin -password <password>
su db2inst1 -c /home/db2inst1/sqllib/adm/db2stop
end script

By default, the wasadmin user ID is used to install the WebSphere Application

Server automatically in the System Automation Application Manager
installation. The password for this user is the password provided in the
parameter OrchestratorPassword. You must replace this value in the script.
3. Make sure that the script has the correct security settings by running the
following command:
chmod 644 /etc/init/saam.conf

If you start System Automation Application Manager now, it will fail because the
agentless adapter is not correctly configured. You configure the agentless adapter
in the next section.
After you configure the agentless adapter, you can start and stop System
Automation Application Manager by running the start saam and stop saam
commands. System Automation Application Manager is automatically started when
the server is started.

Chapter 2. Installing

121

Configuring System Automation Application Manager

Configure System Automation Application Manager to work with IBM Cloud
Orchestrator.

About this task

Note: Before proceeding, ensure that you have completed the task Configuring
the external database server for the high-availability topology on page 119.
During the IBM Cloud Orchestrator installation process, all components and
configuration artifacts that are needed to manage the complete stack with System
Automation Application Manager are installed and prepared. To activate the
System Automation Application Manager management solution, complete the
following procedure:

Procedure
1. Configure the Agentless Adapter:
a. During the installation of the Central Servers and Region Servers, all
necessary automation policies are automatically created on the node where
System Automation Application Manager is installed. These policies are
stored in the /etc/opt/IBM/tsamp/eez/aladapterPolicyPool directory.
b. Identify the domain names for all Agentless Adapter policy XML files that
you want to manage with System Automation Application Manager. The file
for the Central Servers is named SCOcentralALA.xml, and the file for each
Region Server is named <region_name>.xml. The domain name is enclosed
within the <AutomationDomainName> tag. The /etc/opt/IBM/tsamp/eez/
aladapterPolicyPool directory also contains some sample xml files and an
xsd file; ignore these files. You can use the following grep command to
identify the domain names to be managed:
grep -h "<AutomationDomainName>" `ls /etc/opt/IBM/tsamp/eez/aladapterPolicyPool/*.xml
| grep -v Sample` | sort | uniq | cut -d ">" -f 2 | cut -d "<" -f 1

The output of this command is a list of domain names, as shown in the

following example:
RegionKVMCompute
RegionKVMNeutron
RegionVMwareNeutron
SCOcentralALA

These domains are managed by the agentless adapter, as follows:

v You must have one domain, SCOcentralALA, for the central servers.
v Each KVM Region has two agentless adaptor domains:
<region-name>Compute for the compute nodes of this region, and <region
name>Neutron for the Neutron server of the region.
v Each VMware region has only one agentless adapter domain: <region
name>Neutron for the Neutron server of this region.
These regions are managed by the agentless adapter and require a nonroot
SSH access. To provide this nonroot access, the user saamuser is installed on
all servers, with the password specified in the OrchestratorPassword
parameter. You use this user name and password in later steps.
c. Use the cfgeezdmn command to generate one Agentless Adapter domain for
every domain name identified in the previous step. The cfgeezdmn
command requires an X11 display. Use VNC, X11 forwarding, local X11
console, or any other method to provide a valid X11 display before you run

122

IBM Cloud Orchestrator 2.4.0.2: User's Guide

the command. For more information, see Configuring Agentless Adapters in

the System Automation Application Manager, Installation and Configuration
Guide.
To configure the automation domain names identified in step b, click the
Non-clustered Nodes tab, and select Enable local Agentless Adapter
configuration. If you are doing this step for the first time, the configuration
page for the agentless adapter opens automatically. Later, you can open the
configuration page by clicking Configure. On this page, add all domain
names by clicking Add and then click OK.
d. Click the User Credentials tab to enter the user IDs and passwords that are
used by the agentless adapter to communicate with the nodes. You can
either enter the generic saamuser user ID with the same password for all
nodes with agentless adapter resource, or specify the saamuser user ID and
password combination for each individual servers. During the installation of
IBM Cloud Orchestrator, the saamuser user is automatically created for
nonroot access, with the password specified in the OrchestratorPassword
parameter . This user ID and password are used to manage all resources
managed by the Agentless Adapter. To save these settings, click Save and
then click OK.
2. The agentless adapter is now configured. System Automation Application
Manager can now be started. Without a valid configuration, the agentless
adapter start fails. Restart the System Automation Application Manager by
issuing the following commands: stop saam; start saam; stop saam; start
saam. After the agentless adapter is configured, System Automation Application
Manager starts correctly.
3. Configure the System Automation Application Manager Automation Engine.
Use the cfgeezdmn command, as described in Configuring System Automation
Application Manager in the System Automation Application Manager,
Installation and Configuration Guide.
Click the Application Manager tab and click Configure. In the new page, click
the User Credentials tab. The user credentials are the user IDs and passwords
used by the Automation Engine to access the adapter domains: either an
agentless adapter domain or a System Automation for Multiplatforms adapter
domain. Different types of domain are managed differently and require
different credentials for access. The names of the agentless adapter domains are
the same as used in previous steps, and you must use the same combination of
saamuser and password as earlier. The agentless adapter runs locally on the
System Automation Application Manager virtual machine. The agentless
adapter uses nonroot SSH to connect to the virtual machine where the
resources are running. IBM Cloud Orchestrator supports nonroot SSH, and
installs a default user saamuser on all systems managed as agentless adapter
domain. Therefore, you must enter saamuser and the password of saamuser on
the System Automation Application Manager virtual machine for the agentless
adapter domains. The adapter of System Automation for Multiplatforms
domains does not run on the System Automation Application Manager virtual
machine, but on the servers that are managed by the System Automation for
Multiplatforms domains. These servers are accessed by the automation engine,
but not through SSH, and do not require root SSH access. However, System
Automation for Multiplatforms is installed as root user, so you must use the
root user name and password on the virtual machines where the System
Automation for Multiplatforms domain is running. The virtual machines of one
System Automation for Multiplatforms must have the same root password.
Run the following command to display a list of all domains:

Chapter 2. Installing

123

grep "<AutomationDomain>" /etc/opt/IBM/tsamp/eez/policyPool/SCOsaam.xml | sort

| uniq | cut -d ">" -f 2 | cut -d "<" -f 1

The output of this command is a list of domain names, as shown in the

following example:
cs2Domain
RegionKVM
RegionKVMCompute
RegionKVMNeutron
RegionVMware
RegionVMwareNeutron
SCOcentralALA

This list includes all the agentless adapter domains from step 1. It also contains
the System Automation for Multiplatforms domains. The System Automation
for Multiplatforms domain that ensures the high availability of the Central
Server 2 cluster is named cs2Domain. This cluster is running on the Central
Server 2 primary and secondary virtual machines. Each Region has a System
Automation for Multiplatforms domain, which has the same name as the
Region. This cluster runs on the Region Server primary and secondary nodes.
For all of these domains, click Add.... Enter the domain name, user ID,
password, and password confirmation fields and click OK. Repeat this step for
each domain that is listed in the output of the grep command above. Use the
credentials as explained above. Click Save and OK. To exit from cfgeezdmn,
click Done.
Start cfgeezdmn again and switch again to the user credentials tab of the
application manager configuration. Click a domain to select and highlight it.
Now you can click Validate to check the user credential settings for this
domain.Click the Command Shell tab. In User authentication for invoking the
end-to-end automation manager shell, select Use specified user credentials
and enter the eezadmin userid and the password specified in the
OrchestratorPassword parameter. In User authentication for issuing
commands against first-level automation (FLA) domains, select Use FLA
domain access credentials as defined under User credentials. Finally, save
your changes by clicking Save and OK. Close cfgeezdmn by clicking Done. You
have completed the configuration of the automation engine, which can now
access the adapters.
Restart System Automation Application Manager by issuing stop saam; start
saam.
4. Verify that the domains are set up correctly:
eezcs -c "lseezdom"

5. Log on to DASH, which is the web user interface of System Automation

Application Manager: https://<hostname of saam>:16311/ibm/console with the
user eezadmin and its password.
6. Enter the credentials for the DASH to access the automation engine domains.
To do this, click the Explore Automation Domains tab. If the Domain Health
State shows Not logged in, right-click the domain and click Log in. These are
the credentials that the DASH GUI uses to connect to the adapters. Enter the
same user IDs and passwords that you used for the credentials in step 3 for the
automation configuration. The UI shows the same domains as in step 3. If you
want to store the logon information for this UI session, select Save in
credential store. For more information, see Activating an automation policy in
the System Automation Application Manager, Administrator's and User's
Guide.

124

IBM Cloud Orchestrator 2.4.0.2: User's Guide

7. You can now see the state of the System Automation for Multiplatforms
domains. For the domains managed by the agentless adapter, you also have to
active the policy for these domains. To do this, right-click the domain and
select Open Policy Activation Page. This opens a new tab. Select the domain
and, in the right part of the screen, a list of all policies available for this
agentless automation domain is displayed. By default, there is only one.
Right-click it and select Activate Policy.
8. Activate the End-To-End automation policy named SCOsaam.xml. If the
end-to-end automation policy is activated, the automation engine enforces the
policy rules and starts all services. To activate, right-click the SCOsaam policy
and select Open Policy Activation Page. This opens a new tab. Select the
domain and, in the right part of the screen, a list of all policies available for
this agentless automation domain is displayed. By default, there is only one.
Right-click it and select Activate Policy. Fore more information, read Activating
an automation policy in the System Automation Application Manager,
Administrator's and User's Guide.
9. To manage the end-to-end automation, switch to Operate end-to-end resources.

Results
System Automation Application Manager is configured and the policies are
activated. System Automation Application Manager checks the status of the IBM
Cloud Orchestrator management services and starts them if needed. After the
services are started, System Automation Application Manager detects any outage
of the IBM Cloud Orchestrator management services and automatically restarts
them.
If you want to stop any services, see Controlling the management stack on page
243.

Strengthening security
Complete these tasks to strengthen the security of your IBM Cloud Orchestrator
environment.
For information about port management and security, see the IBM Cloud
Orchestrator Security Hardening Guide.

Changing the Deployment Service passwords

After you install the Deployment Service, you can change the default passwords
on the Deployment Service node in accordance with security best practices.

Procedure
1. Change the password of the admin user in Keystone, as follows:
a. Log in to the Deployment Service node as a root user.
b. Run the following command:
source /root/keystonerc

c. Find the ID of the admin user:

keystone user-get admin

d. Update the admin password:

keystone user-password-update --pass new_password admin_user_id

e. Run the following command to encrypt the new password:

/usr/bin/openstack-obfuscate new_admin_password

Chapter 2. Installing

125

Make a note of the output of this command. You use this value
(encrypted_new_admin_password) in the remaining parts of this step.
f. Create a backup of the /root/keystonerc and /root/openrc files:
cp -p /root/keystonerc /root/keystonerc.orig
cp -p /root/openrc /root/openrc.orig

g. Edit the /root/keystonerc and /root/openrc files to update the OS_PASSWORD

entry to the encrypted new value as follows:
v Before:
export OS_PASSWORD=$(openstack-obfuscate -u old_admin_password)

v After:
export OS_PASSWORD=$(openstack-obfuscate -u encrypted_new_admin_password)

h. Verify that the updated password works:

source /root/keystonerc
keystone user-list

2. Change the password of the database users for OpenStack (ceilometer, glance,
heat, keystone, nova) as follows:
Tip: Depending on your local security standards, you can enable nologin
support for Deployment Service user identifiers as described in the IBM Cloud
Orchestrator V2.4 Hardening Guide. The nologin approach might remove the
need to manage passwords for individual user identifiers.
a. Log in to the Deployment Service node as a root user.
b. Change the password for the specified users by running the following
commands. After each command, you must specify the new password.
passwd
passwd
passwd
passwd
passwd

ceilometer
glance
heat
keystone
nova

c. Find the connection or sql_connection entry in each of the corresponding

configuration files:
v /etc/ceilometer/ceilometer.conf
v /etc/glance/glance-api.conf
v /etc/glance/glance-registry.conf
v /etc/heat/heat.conf
v /etc/keystone/keystone.conf
v /etc/nova/nova.conf
Example:
grep -Fnr connection /etc/keystone/keystone.conf

Example output:
28:connection =
W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==

d. For each entry identified in the previous step, decode the DB2 connect
information:
Example:
openstack-obfuscate -u connection_details

Example output:
ibm_db_sa://userid:old_password@ip_address:50000/openstac

e. For each entry, encrypt the DB2 connect information with the new password

126

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Example:
openstack-obfuscate ibm_db_sa://userid:new_password@ip_address:50000/openstac

Example output:
new_connection_details

Make a note of the output of this command. You use this value in the
remaining parts of this step.
f. Edit the corresponding name.conf configuration file to comment out the
original connection or sql_connection entry, and add the encrypted new
password information in a new entry, as shown in the following example:
# connection = W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==
connection = W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmFyamNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==

g. Run the following command to check that all files were changed:
grep -Fnr connection /etc

h. Change directory to the /etc/init.d directory.

cd /etc/init.d

i. Find the OpenStack services:

ls openstack-*

j. Restart each OpenStack service, one by one:

service openstack-service_name restart

k. Verify that the updated passwords work:

source /root/keystonerc
ds template-list

Changing the various passwords

Change the password for several different types of users in the IBM Cloud
Orchestrator environment.
v Built-in users:
Changing the admin password on page 128
Changing the bpm_admin and tw_admin passwords on page 129
Changing the password for OpenStack service users on page 130
v Database users:
Changing the db2inst1 password on page 131
Changing the bpmuser password on page 133
Changing the database passwords used by OpenStack components on page
134
Changing the database passwords used by the Administration user
interface on page 135
v vCenter user:
Changing the vCenter password on page 136
Important:
v During installation and upgrade, IBM Cloud Orchestrator passwords can contain
only alphanumeric characters and underscores. Spaces, hyphens, and other
special characters are not allowed.
v Some of the steps in this topic refer to Central Server 2 or Region Server. In a
high-availability installation, remember to repeat these steps on the secondary
Central Server 2 or the secondary Region Server.

Chapter 2. Installing

127

v In a demo or proof-of-concept installation, Central Server 2 components are

found on Central Server 1.
v If you use external database support, contact your database administrator to
change the password according to the external IBM DB2 configuration.

Changing the admin password

The admin user is the default Cloud Administrator user. The admin user is also used
for internal connectivity across the following IBM Cloud Orchestrator components:
v Workload Deployer
v Public Cloud Gateway
v VMware discovery
To change the admin password, complete the following steps:
1. Change the password in the IBM Cloud Orchestrator user interface, in either of
the following ways:
Important: After you change the password, you cannot continue to work with
the pattern management user interface until you complete step 2 of this
procedure. However the Administration user interface and Self-service user
interface can still be used.
v Use the Administration user interface:
a. Log in to the Administration user interface as a Cloud Administrator.
b. In the navigation pane on the left, click ADMIN > Identity Panel >
Users.
c. Select the admin user. From the Actions column on the right, click Edit.
d. Enter the new password in the Password and Confirm Password fields.
e. Click Update User. Close your browser.
v Use the Self-service user interface:
a. Log in to the Self-service user interface as a Cloud Administrator.
b. Click CONFIGURATION > Domain, and then click Users.
c. Select the admin user. From the Actions menu on the left, click Edit User.
d. Enter the new password in the Password and Confirm Password fields.
e. Click Ok. Close your browser.
2. Log on to Central Server 3 and restart the Workload Deployer service:
v If you are not using the IBM Cloud Orchestrator high-availability solution,
run the following command:
service iwd restart

v If you are using the IBM Cloud Orchestrator high-availability solution, log in
to the System Automation Application Manager user interface, and initiate a
restart of the Workload Deployer resource.
3. Log on to Central Server 2, and complete the following steps:
a. Run the following command to encrypt the new password:
/usr/bin/openstack-obfuscate new_admin_password

Make a note of the output of this command. You use this value
(encrypted_new_admin_password) in the remaining parts of this step.
b. Create a backup of the /root/keystonerc file:
cp -p /root/keystonerc /root/keystonerc.orig

128

IBM Cloud Orchestrator 2.4.0.2: User's Guide

c. Edit the /root/keystonerc file and replace the encrypted value in the
OS_PASSWORD entry with the encrypted new value as follows:
v Before:
export OS_PASSWORD=$(openstack-obfuscate -u encrypted_old_admin_password )

v After:
export OS_PASSWORD=$(openstack-obfuscate -u encrypted_new_admin_password )

4. Edit the configuration files on the various servers as listed in Table 1, to update
the admin_password entry to the encrypted new value as follows:
v Before:
admin_password=old_admin_password

v After:
admin_password=encrypted_new_admin_password
Table 11. Configuration files that contain the admin password
Server

Component

Configuration files

Central Server 1

Ceilometer

/etc/ceilometer/
ceilometer.conf

Region Server

Cinder

/etc/cinder/cinder.conf

Glance

/etc/glance/glanceregistry.conf
/etc/glance/glance-api.conf

Heat

/etc/heat/heat.conf

Nova

/etc/nova/nova.conf

VMware Discovery (VMware /etc/vmware-discovery.conf

only)
Neutron Server

Neutron

/etc/neutron/neutron.conf

In the /etc/nova/nova.conf file, update also the following entry:

neutron_admin_password=encrypted_new_admin_password

In the /etc/neutron/neutron.conf file, update also the following entry:

nova_admin_password=encrypted_new_admin_password

Note: It might be that after changing the admin password, and you try to login
that you are forbidden from doing so. When this happens, it is because the
keystone process has failed. If you have difficulties logging in (all passwords
refused) than you should check the keystone process and restart it if necessary.
5. If the IBM Cloud Orchestrator system is configured to attach to a Public Cloud
Gateway, then you must update the keystone administrator credentials for the
Public Cloud Gateway in the /opt/ibm/pcg/etc/admin.json. The details of the
process are found at: Changing the Keystone administrator password on
page 693.

Changing the bpm_admin and tw_admin passwords

The bpm_admin and tw_admin users are required by Business Process Manager for
internal operations.
To change the bpm_admin password, complete the following steps:
1. Log on to WebSphere Application Server:
https://$central-server2:9043/ibm/console/logon.jsp

Chapter 2. Installing

129

2.
3.
4.
5.

Expand Users and Groups, and click Manager Users.

Select bpm_admin.
In the User Properties panel, set the password, confirm it, and click Apply.
On Central Server 2, change the configuration files as follows:
a. Back up the configuration files:
v On the primary Central Server 2, and for installations that are not highly
available, back up the following files:
/opt/ibm/BPM/v8.5/profiles/DmgrProfile/properties/
soap.client.props
/opt/ibm/BPM/v8.5/profiles/Node1Profile/properties/
soap.client.props
v On the secondary Central Server 2 for installations that are highly
available, back up only the following file:
/opt/ibm/BPM/v8.5/profiles/Node2Profile/properties/
soap.client.props
b. Edit each of the soap.client.props files listed in step 5a to find the
com.ibm.SOAP.loginUserid=bpm_admin entry, and update the associated
com.ibm.SOAP.loginPassword entry to specify the new password as plain
text:
com.ibm.SOAP.loginUserid=bpm_admin
com.ibm.SOAP.loginPassword=new_bpm_admin_password

c. Encrypt the password:

v On the primary Central Server 2, and for installations that are not highly
available, run the following two commands:
/opt/ibm/BPM/v8.5/bin/PropFilePasswordEncoder.sh
/opt/ibm/BPM/v8.5/profiles/DmgrProfile/properties/soap.client.props
com.ibm.SOAP.loginPassword
/opt/ibm/BPM/v8.5/bin/PropFilePasswordEncoder.sh
/opt/ibm/BPM/v8.5/profiles/Node1Profile/properties/soap.client.props
com.ibm.SOAP.loginPassword

v On the secondary Central Server 2 for installations that are highly

available, run the following command:
/opt/ibm/BPM/v8.5/bin/PropFilePasswordEncoder.sh
/opt/ibm/BPM/v8.5/profiles/Node2Profile/properties/soap.client.props
com.ibm.SOAP.loginPassword

6. Follow the additional configuration steps described in the Business Process

Manager documentation.
To change the password of the tw_admin user, complete the same procedure as
described for the bpm_admin user, but omit step 5 and step 6. Do not modify any
soap.client.props files.

Changing the password for OpenStack service users

OpenStack has several service users: ceilometer, cinder, glance, heat, neutron,
and nova.
By default, when these service users are created during installation, they are
assigned the same password as the admin user. To change the password of any of
these service users, complete the following steps:
1. Log in to the Administration user interface as a Cloud Administrator.
2. In the navigation pane on the left, click ADMIN > Identity Panel > Users.

130

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. Select the user that you want to edit. From the Actions column on the right,
click Edit.
4. Enter the new password in the Password and Confirm Password fields.
5. Click Update User.

Changing the db2inst1 password

The db2inst1 password must be changed in the operating system where the IBM
DB2 instance is installed and in the Workload Deployer configuration.
1. Update the db2inst1 password in the operating system, as follows:
a. Log on to Central Server 1 as the root user.
b. Change the operating-system password for the IBM DB2 database user
db2inst1 and for the Keystone database user keystone by running the
following commands. After each command, you must enter the new
password.
passwd db2inst1
passwd keystone

c. Log on to each Region Server as a root user.

d. Identify the database user IDs used by Glance, Nova, Cinder, and IBM
Cloud Orchestrator to access the database:
egrep "gla|cin|nov" /etc/passwd

Example output:
nova:x:503:503::/home/nova:/bin/sh
glance:x:506:506::/home/glance:/bin/bash
cinder:x:509:509::/home/cinder:/bin/bash

e. Update the operating-system password for the database user IDs that you
identified in the previous step by running the following commands. After
each command, you must enter the new password.
passwd glance
passwd cinder
passwd nova

2. On Central Server 2, update the DB2-related password for the Keystone service
in the OpenStack configuration file, as shown in the following example:
a. Find the connection entry in the Keystone configuration file:
grep -Fnr connection /etc/keystone/keystone.conf

Example output:
28:connection =
W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==

b. Decode the DB2 connect information:

openstack-obfuscate
-u W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==
ibm_db_sa://keystone:old_password@DB2_host_IP_address:50000/openstac

where DB2_host_ip_address is the IP address of Central Server 1.

c. Encrypt the DB2 connect information with the new password:
openstack-obfuscate ibm_db_sa://keystone:new_password@DB2_host_IP_address:50000/openstac
W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmFyamNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==

Make a note of the output of this command. You use this value in the
remaining parts of this step.

Chapter 2. Installing

131

d. Edit the /etc/keystone/keystone.conf file to comment out the original

connection entry, and add the encrypted new password information in a
new entry, as shown in the following example:
# connection = W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==
connection = W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmFyamNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA

3. On each Region Server, update the DB2-related password for the Cinder,
Glance, and Nova services in the OpenStack configuration files.
Important:
v Do not reuse any obfuscated connection string in other connection strings.
v Deobfuscate and obfuscate step-by-step each line with the new password.
a. If the region is a non-shared DB2 region, log on to each Region Server as a
root user. Otherwise, log on to Central Server 1 as a root user.
b. To find all the places in the configuration files that have to be changed, run
the following command:
grep -Fnr sql_connection /etc

Example output:
/etc/nova/nova.conf:70:sql_connection= nova_connection_details
/etc/cinder/cinder.conf:17:sql_connection = cinder_connection_details
/etc/glance/glance-registry.conf:27:sql_connection = glance-registry_connection_details
/etc/glance/glance-api.conf:32:sql_connection = glance-api_connection_details

c. For each entry identified in the previous step, decode the DB2 connect
information:
openstack-obfuscate -u connection_details
ibm_db_sa://userid:old_password@DB2_host_IP_address:50000/openstac

where DB2_host_ip_address is the IP address of Central Server 1.

d. Encrypt the DB2 connect information with the new password:
openstack-obfuscate ibm_db_sa://userid:new_password@DB2_host_IP_address:50000/openstac
new_connection_details

Make a note of the output of this command. You use this value in the
remaining parts of this step.
e. Edit the corresponding name.conf configuration file to comment out the
original sql_connection entry, and add the encrypted new password
information in a new entry.
f. Run the following command again to check that all files were changed:
grep -Fnr sql_connection /etc

Example output:
/etc/nova/nova.conf:70:#sql_connection= orig_nova_connection_details
/etc/nova/nova.conf:70:sql_connection= new_nova_connection_details
/etc/cinder/cinder.conf:17:#sql_connection = orig_cinder_connection_details
/etc/cinder/cinder.conf:17:sql_connection = new_cinder_connection_details
/etc/glance/glance-registry.conf:27:#sql_connection = orig_glance-registry_connection_details
/etc/glance/glance-registry.conf:27:sql_connection = new_glance-registry_connection_details
/etc/glance/glance-api.conf:32:#sql_connection = orig_glance-api_connection_details
/etc/glance/glance-api.conf:32:sql_connection = new_glance-api_connection_details

The output should include two entries per connection: the original entry
(now commented out) and the new entry.
4. On Central Server 1, restart all of the OpenStack services, as described in
Starting or stopping IBM Cloud Orchestrator on page 221. For example, for
an installation that is not highly available, run the following commands:

132

IBM Cloud Orchestrator 2.4.0.2: User's Guide

/opt/ibm/orchestrator/scorchestrator/SCOrchestrator.py --stop -p openstack

/opt/ibm/orchestrator/scorchestrator/SCOrchestrator.py --start -p openstack

5. Update the db2inst1 password in Workload Deployer, as follows:

a. Log on to Central Server 3 as the root user.
b. Stop the Workload Deployer service:
service iwd stop

c. Change the password:

service iwd setdb2host DB2_host_ip_address 50000 db2inst1 new_password

where DB2_host_ip_address is the IP address of Central Server 1.

d. Start the Workload Deployer service:
service iwd start

e. Verify that the Workload Deployer components are running:

service iwd status

If any Workload Deployer components are not running, restart the

Workload Deployer service:
service iwd restart

Changing the bpmuser password

The bpmuser user is the IBM DB2 user for Business Process Manager.
The bpmuser password must be changed in the operating system where the IBM
DB2 instance is installed, and in the WebSphere Application Server console that is
used by Business Process Manager.
1. Update the bpmuser password in the operating system, as follows:
a. Log on to Central Server 1 as the root user.
b. Change the operating-system password for the bpmuser database user:
passwd bpmuser

2. Update the password in WebSphere Application Server, as follows:

a. Log on to the Business Process Manager WebSphere Application Server
console as the bpm_admin user:
https://$central-server-2:9043/ibm/console/logon.jsp

b. Select Resources.
c. Select JDBC.
d. Select Data sources and click BPM Business Space data source.
e. Click the option JAAS - J2C authentication data.
f. Click BPM_DB_ALIAS, and insert the new password. Click Apply to
validate the change.
g. Repeat step 2f for the CMN_DB_ALIAS and PDW_DB_ALIAS values.
h. When prompted to save your changes, click Save directly to the master
configuration.
i. Test the DB connection by clicking Test connection and selecting BPM
Business Space data source.
j. Restart Business Process Manager.
If you get errors while synchronizing the changes, log out and log in again, and
try to modify the password again.
For more information about updating passwords in WebSphere Application
Server, see Updating the data source authentication alias.
Chapter 2. Installing

133

Changing the database passwords used by OpenStack components

For security reasons, each OpenStack component has its own database user and
password.
To change the database password for an OpenStack component, complete the
following steps:
1. If changing the Keystone database password, shut down the Central Server
components. If changing the database password for any other OpenStack
component, shut down the Region Server components. For more information
about how to start and shut down components, see Starting or stopping IBM
Cloud Orchestrator on page 221.
2. Identify the database user name for the component. For a production topology
with a shared database, where all Central Servers and Region Servers are
installed on Central Server 1, the database user name is suffixed with a string
that matches the region type: for example, vmw for a VMware region, or kvm for
a KVM region. Refer to the table below for the database user names.
3. Update the database user password in the operating system, as follows:
a. Log on to the database server as the root user.
b. Change the operating-system password for the database user:
passwd database_user_name

4. Find the connection or sql_connection entry in each relevant configuration file

as listed in the table below.
Example:
grep -Fnr connection /etc/keystone/keystone.conf

Example output:
28:connection =
W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==

5. For each entry identified in the previous step, decode the DB2 connect
information:
openstack-obfuscate -u connection_details

Example:
openstack-obfuscate
-u W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==

The output is in the following format:

ibm_db_sa://userid:old_password@DB2_host_IP_address:50000/openstac

where DB2_host_ip_address is the IP address of Central Server 1.

Example output:
ibm_db_sa://keystone:[email protected]:50000/openstac

6. For each entry, encrypt the DB2 connect information with the new password:
Example:
openstack-obfuscate ibm_db_sa://userid:new_password@DB2_host_IP_address:50000/openstac

Example output:
new_connection_details

Make a note of the output of this command. You use this value in the
remaining parts of this step.

134

IBM Cloud Orchestrator 2.4.0.2: User's Guide

7. Edit the corresponding name.conf file to comment out the original connection
or sql_connection entry, and add the encrypted new password information in a
new entry, as shown in the following example:
# connection = W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==
connection = W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmFyamNuZmZqMGVxQDE3Mi4xOS41LjE2MDo1MDAwMC9iY3JhZmducA==

8. When you change the Neutron password, remember also to change the
password in the configuration file of the Neutron network node.
9. Start the IBM Cloud Orchestrator components that were shut down in step 1 on
page 134.
Table 12.
Component

Configuration file

Configuration key

Default database user

name

Identity

/etc/keystone/keystone.conf

connection

keystone

Compute

/etc/nova/nova.conf

connection

nova

Image

/etc/glance/glance-api.conf

sql_connection

glance

/etc/glance/glance-registry.conf
Storage

/etc/cinder/cinder.conf

connection

cinder

Network

/etc/neutron/neutron.conf

connection

neutron

Orchestration

/etc/heat/heat.conf

connection

heat

Telemetry

/etc/ceilometer/ceilometer.conf

connection

ceilometer

Changing the database passwords used by the Administration user

interface
The Administration user interface, which is based on the OpenStack Horizon
component, stores session information in an SQL database.
1. Update the dash password in the operating system, as follows:
a. Log on to Central Server 1 as the root user.
b. Change the operating-system password for the dash database user:
passwd dash

2. Log in to Central Server 2 and encrypt the database password:

openstack-obfuscate new_database_password

Example output:
encrypted_new_database_password

Make a note of the output of this command. You use this value in the next
step.
3. On Central Server 2, edit the /etc/openstack-dashboard/local_settings file as
follows:
a. Locate the DATABASES section, which is similar to the following text:
# A dictionary containing the settings for all databases to be used with
# Django. It is a nested dictionary whose contents maps database aliases
# to a dictionary containing the options for an individual database.
DATABASES = {
default: {
ENGINE: ibm_db_django,
NAME: openstac,
USER: dash,
PASSWORD: utils.decode_opt(W0lCTTp2MV1yaHYzMjU4ZQ==),

Chapter 2. Installing

135

HOST: 172.19.8.65,
default-character-set: utf8
},
}

b. Replace the encrypted password in the PASSWORD entry with the

encrypted_new_database_password value, making sure that you keep the
single quotes.
c. Save the /etc/openstack-dashboard/local_settings file.
4. On Central Server 2, restart the Administration user interface:
service httpd restart

Changing the vCenter password

When you change the vCenter password, run the following steps in your IBM
Cloud Orchestrator environment:
1. Shut down the Region Server components. For more information about how to
start and shut down components, see Starting or stopping IBM Cloud
Orchestrator on page 221.
2. Run the following command to obtain the encrypted password:
/usr/bin/openstack-obfuscate new_vCenter_password

3. Edit the corresponding name.conf file to comment out the original entry, and
add the encrypted new password information in a new entry. The configuration
files and keys are listed in the following table:
Table 13.
Component

Configuration file

Configuration key

Compute

/etc/nova/nova.conf

host_password

Image

/etc/glance/glance-api.conf

vmware_server_password

Storage

/etc/cinder/cinder.conf

vmware_host_password

Telemetry

/etc/ceilometer/ceilometer.conf

host_password

4. Start the Region Server components.

Replacing the existing certificates

You can replace existing certificates to strength security in your environment.

Discovering the keystore password

The SSL certificate used by the IBM HTTP Server is contained in a file called a
certificate store. This file is protected by a password. By default, this password is
set to the value of the master administrator password that is set during the IBM
Cloud Orchestrator installation. If you cannot remember this password, complete
the following steps to retrieve this value from an encrypted Chef data bag:
1. Log on to the Deployment Server in your environment (that is, the server that
was used to do the installation), and gain root privilege with the su
command.
2. Load the OpenStack environment variables by running the following
command:
source /root/keystonerc

3. Show a list of the installation tasks that were run:

ds job-list

136

IBM Cloud Orchestrator 2.4.0.2: User's Guide

4. Depending on the installation topology that you used, one or more jobs is
listed:
v If only one job is listed, make a note of the ID (that is, the long hexadecimal
string in the ID column).
v If two or more jobs are listed, make a note of the ID for the Central Server
job.
v If multiple IBM Cloud Orchestrator installations were deployed from the
same deployment server, use the time stamps to identify the correct Central
Server job.
Tip: If it is still not possible to identify the correct job:
a. Use the remaining steps in this section to discover the password used for
the jobs. Repeat the steps as necessary to identify the password for each
job ID.
b. When you generate the certificate requests, as described in the next
section, try each password in turn until you find the correct password to
unlock the certificate store.
5. Change to the Chef configuration directory:
cd /etc/chef

6. Locate the file containing the encryption key:

cat /etc/chef/databag_secret

7. Obtain a list of the Chef data bags:

knife data bag list

8. Identify the data bag whose name is user-OC_ENV-<guid>, where <guid> is the
ID of the installation task as identified in step 4.
9. List the items in the data bag:
knife data bag show <data_bag_name>

where the value <data_bag_name> is the entire string user-OC_ENV-<guid>.

Ensure that there is an entry called ihs_admin.
10. Display the value of the ihs_admin password:
knife data bag show <data_bag_name> ihs_admin --secret-file /etc/chef/databag_secret

This command returns the ihs_admin ID and password.

11. Make a note of the password, which is required for all operations on the IBM
HTTP Server SSL certificate store.

Generating the certificate requests

IBM Cloud Orchestrator requires two separate certificates: one for Central Server 2
and one for the Workload Deployer server. To generate the certificate requests,
perform the following steps:
1. Logon to the Central Server 2 (in high-availability environment, the primary
Central Server 2) and gain root privilege with su.
2. Change directory to /opt/IBM/HTTPServer/bin
3. Back up the existing certificate store:
cp key.kdb key.kdb.bak

4. Check that the password from the first section works and get a list of the
certificates in the certificate store:
./gskcmd -cert -list -db key.kdb -pw <password>

Chapter 2. Installing

137

5. The output should show two certificates . The name of the first certificate is the
fully qualified domain name (FQDN) of the virtual address of Central Server
2. Make a note of this name because you are required to enter the name in the
following steps when <fqdn-cs2> is specified. <fqdn-iwd> is the FQDN of the
Workload Deployer server (this is needed only if you installed the Workload
Deployer component). The second certificate name starts with a long numeric
label followed by a number of parameters with the value unknown. This is an
internal certificate used by the IBM HTTP Server to forward traffic to the IBM
Cloud Orchestrator user interface server on port 7443. You must not modify or
delete this certificate.
6. Remove the existing SSL certificates by running the following commands:
./gskcmd -cert -delete -label <fqdn-cs2> -db key.kdb -pw <password>
./gskcmd -cert -delete -label <fqdn-iwd> -db key.kdb -pw <password>

Note: You must run the second command only if you installed the Workload
Deployer component.
7. Create the certificate requests by running the following commands:
./gskcmd -certreq -create -label <fqdn-cs2> \
-dn "CN=<fqdn>,O=<your organization>,OU=<your division>,C=<your country code>" \
-db key.kdb -file certreq_cs2.arm -pw <password>
./gskcmd -certreq -create -label <fqdn-iwd> \
-dn "CN=<fqdn>,O=<your organization>,OU=<your division>,C=<your country code>" \
-db key.kdb -file certreq_iwd.arm -pw <password>

Note: You must run the second command only if you installed the Workload
Deployer component.
8. In the current directory, locate the certreq_cs2.arm file and, if you installed the
Workload Deployer component, the certreq_cs2.iwd file and upload them to
your Certificate Authority (CA) for signing.

Installing the new certificates

To install the new certificates, perform the following steps:
1. When the CA returns the signed certificates, download them as
certreq_cs2.arm and certreq_cs2.iwd.
2. Import root and intermediate certificates. Consult the Certificate Authority's
online help for details about the required root and intermediate certificates.
Download the certificates and import them by running the following command
for each certificate:
./gskcmd -cert -import -target key.kdb -pw <password> -file <downloaded certificate file>

3. Add the new SSL certificates by running the following commands:

./gskcmd -cert -receive -db key.kdb -pw <password> -file cert_cs2.arm
./gskcmd -cert -receive -db key.kdb -pw <password> -file cert_iwd.arm

Note: You must run the second command only if you installed the Workload
Deployer component.
4. Check that the certificates were added to the certificate store by running the
following command:
./gskcmd -cert -list -db key.kdb -pw <password>

5. Make the Central Server 2 certificate the default certificate by running the
following command:
./gskcmd -cert -setdefault -db key.kdb -pw <password> -label <fqdn_cs2>

138

IBM Cloud Orchestrator 2.4.0.2: User's Guide

6. Check the default certificate by running the following command and add a
reminder to your calendar for the expiration date of the certificate:
./gskcmd -cert -getdefault -db key.kdb -pw <password>

Testing the new certificate

Note: If your IBM Cloud Orchestrator environment is highly available, shut down
the secondary Central Server 2 before performing the following procedure.
1. Restart the IBM HTTP Server to use the new certificate by running the
following command:
service ihs-apachectl restart

2. Test the new certificate by using a browser to access the address

https://<fqdn-cs2>:8443/dashboard.
3. If the browser cannot connect, check the IBM HTTP Server log file by running
the following command:
tail /opt/IBM/HTTPServer/logs/error_log

If you see the following message

SSL0208E: SSL Handshake Failed, Certificate validation error.

a problem with the root and intermediate certificates occurred. Recheck that the
correct intermediate and root certificates were imported from the CA. If you
have to import more certificates, make sure that the default certificate selection
does not change and correct it, if needed.
4. Once the browser connects, use the browser to examine the certificate and
confirm it is as expected. If it is not the correct certificate, recheck which
certificate is the default as detailed before.

Updating the WebSphere trust store

You must update the certificate in the WebSphere trust store so that WebSphere can
establish SSL connections to the IBM HTTP Server in order to make REST calls.
1. Logon to the WebSphere Console. Use the browser to access
https://<fqdn-cs2>:9043/ibm/console
The user ID is bpm_admin and the password is the master password specified
when you installed IBM Cloud Orchestrator.
2. Replace the SSL Certificates in the WebSphere trust store:
a.
b.
c.
d.
e.
f.
g.
h.
i.
j.
k.

Navigate to Security > SSL Certificate and key management.

Choose Key stores and certificates.
Keep the default of SSL keystores in the dropdown list.
Click CellDefaultTrustStore and then Personal certificates.
Select the entry where the Alias matches the Central Server 2 FQDN of the
certificate you requested above and press Delete.
Save the change direct to the master configuration.
Click Import....
Choose Key store file and enter /opt/IBM/HTTPServer/bin/key.kdb for the
key file name.
Change Type to CMSKS.
Enter the keystore password.
Click Get Key File Aliases.

Chapter 2. Installing

139

l. Choose the certificate that matches the Central Server 2 FQDN from the
dropdown list.
m. Enter the same label (the Central Server 2 FQDN) into the Imported
certificate alias field.
n. Press OK.
Note: WebSphere will import the other certificates from the trust chain
automatically.
o. Save the change direct to the master configuration.
p. Repeat the steps from e to o for the Workload Deployer FQDN.
3. Restart WebSphere. At the terminal window enter:
service bpm-server restart

Updating the certificate on the secondary Central Server 2

Only for high-availability environments of IBM Cloud Orchestrator, perform the
following additional steps:
1. Start up the secondary Central Server 2 node, logon and gain root privilege
with su.
2. Change directory to /opt/IBM/HTTPServer/bin.
3. Back up the existing certificate store:
cp key.kdb key.kdb.bak

4. Copy the certificate store from the primary node to the secondary node:
scp <cs2 primary node hostname>:/opt/IBM/HTTPServer/bin/key.kdb

5. If the secondary Central Server 2 was only suspended during the work on
primary Central Server 2, you must restart BPM on the secondary node so that
it uses the new certificate:
service bpm-server restart

6. You do not need to restart the IBM HTTP Server on the secondary node since it
will not normally be running and will be started automatically if the primary
Central Server 2 node fails.

Updating the certificate on the Workload Deployer server

To replace certificate on the Workload Deployer server (if you installed the
Workload Deployer component), perform the following steps:
1. Log on to Central Server 3 (the Workload Deployer server).
2. Stop the iwd service by running the following command:
service iwd stop

3. Back up the Workload Deployer server certificate located in the following path:
/opt/ibm/rainmaker/purescale.app/private/expanded/ibm/rainmaker.rest-4.1.0.0/config/rm.p12

4. Back up the Workload Deployer kernel services truststore located in

/opt/ibm/maestro/maestro/usr/resources/security/KSTrustStore.jks.
5. Copy the Workload Deployer server certificate to the following path:
/opt/ibm/rainmaker/purescale.app/private/expanded/ibm/rainmaker.rest-4.1.0.0/config/rm.p12

6. Remove the existing SSL certificates by running the following commands:

keytool -delete
keytool -delete

-keystore KSTrustStore.jks -storetype JKS -storepass pureScale -alias <fqdn-cs2> -v

-keystore KSTrustStore.jks -storetype JKS -storepass pureScale -alias <fqdn-iwd> -v

7. Import the Workload Deployer server certificate to kernel services truststore:

140

IBM Cloud Orchestrator 2.4.0.2: User's Guide

source /etc/profile.d/jdk_iwd.sh
keytool -v -importkeystore \
-srckeystore /opt/ibm/rainmaker/purescale.app/private/expanded/ibm/rainmaker.rest-4.1.0.0/config/rm.p12 \
-srcstoretype PKCS12 -destkeystore /opt/ibm/maestro/maestro/usr/resources/security/KSTrustStore.jks \
-deststoretype JKS -deststorepass pureScale -srcstorepass <password>

8. Edit the configuration file /opt/ibm/rainmaker/purescale.app/private/

expanded/ibm/rainmaker.rest-4.1.0.0/config/https-server.config and
replace the passwords and the keystore path. Note that the passwords must be
encoded by using the utility provided by smash:
/opt/ibm/rainmaker/purescale.app/zero encode <your-password>
/config/https/sslconfig = {
"keyStore": "${/config/dependencies/ibm:rainmaker.rest}/config/rm.p12",
"keyStorePassword": "<encoded-password like: <xor>Lz4sLChvLTs=>",
"keyStoreType": "PKCS12",
"trustStore": "${/config/dependencies/ibm:rainmaker.rest}/config/rm.p12",
"trustStorePassword": "<xor>Lz4sLChvLTs=",
"trustStoreType": "PKCS12"

9. Start the iwd service by running the following command:

service iwd start

To replace the certificate for the Workload Deployer command line, perform the
following steps:
1. Log on to Central Server 3 (Workload Deployer server).
2. Switch to /opt/ibm/rainmaker/purescale.app/private/expanded/ibm/
rainmaker.ui-4.1.0.0/public/downloads.
3. Unzip the file deployer.cli-5.0.0.0-<buildid>.zip, to the current folder, for
example:
unzip -q deployer.cli-5.0.0.0-20140815194859.zip

Note: There will be only one file that matches this naming scheme.
4. Move the file deployer.cli-5.0.0.0-<buildid>.zip to a backup folder.
5. Copy the Workload Deployer server certificate to the files deployer.cli/lib/
cb.p12 and deployer.cli/lib/deployer-ssl.p12, overwriting the existing files.
Make sure the files have the correct access rights (640):
chmod 640 deployer.cli/lib/cb.p12 deployer.cli/lib/deployer-ssl.p12

6. Import certificate to the Workload Deployer CLI keystore:

source /etc/profile.d/jdk_iwd.sh;keytool -v -importkeystore -srckeystore deployer.cli/lib/cb.p12
-srcstoretype PKCS12 -destkeystore deployer.cli/lib/deployer-ssl.jks
-deststoretype JKS -deststorepass ra1nmaker -srcstorepass <password>

7. Delete file deployer.cli-5.0.0.0-<buildid>.zip.

8. Archive the content of the deployer.cli directory into a zip file having the
same name as original file:
zip -q -r deployer.cli-5.0.0.0-<buildid>.zip deployer.cli

Testing the new Workload Deployer server certificate

To test the new Workload Deployer server certificate, perform the following steps:
1. Log in to the Self-service user interface at https://<fqdn-cs2>:8443.
2. Manually modify URL to point to https://<fqdn-cs2>:8443/resources/
instances/. The response should be a list of instances in JSON format (it might
be empty depending on the state of the environment).
3. If the browser cannot connect, check the error in the IBM HTTP Server log file
in the /opt/IBM/HTTPServer/log/ directory.
Chapter 2. Installing

141

Accessing Workload Deployer databases with a different user

You can access the Workload Deployer databases with a different user.
Perform the following steps:
1. Stop the Workload Deployer component. Verify that it is stopped by running
the service iwd status command.
2. On DB2 node, create an additional user account to access the Workload
Deployer databases (<newuser>). Use Linux commands like adduser and passwd
to create the user. User does not have to belong to any special group.
3. From DB2 instance owner account (by default db2inst1), run the following
commands to grant to <newuser> the access to the Workload Deployer
databases:
echo db2 CONNECT TO STORHOUS
echo db2 GRANT DBADM ON DATABASE TO USER <newuser>
echo db2 CONNECT RESET

Repeat the same commands for the RAINMAKE database.

4. By default all the tables in the Workload Deployer databases are created under
db2inst1 schema. To move the tables to <newuser>, follow the instructions at
http://www-01.ibm.com/support/docview.wss?uid=swg21289066.
5. On the Workload Deployer node, replace the old database connection
credentials with the new ones by editing the /etc/init.d/iwd-env file and
replacing the values for DB2_USER and DB2_PASS.
Example of valid content:
export DB2_USER=iwduser
export DB2_PASS=<xor>Lz4sLChvLTs=

To get encrypted password, run the following command:

/opt/ibm/rainmaker/purescale.app/zero passwordTool -e <password for newuser>

For example:
/opt/ibm/rainmaker/purescale.app/zero passwordTool -e veryS3cure;
<xor>KTotJgxsPCotOg==

6. Start the Workload Deployer component.

Configuring options to delete running instances

This topic describes how you configure options to handle deleted but still running
instances.
Nova runs a periodic process to clean up 'deleted but still running' instances. It is
configurable, both at the task level and at the action level.
In the nova.conf file, set one of these:
#To take no action when an instance is found
running_deleted_instance_action=noop (or log)
#To disable the periodic task altogether
running_deleted_instance_poll_interval = 0

where for:
running_deleted_instance_action
You can set:

142

IBM Cloud Orchestrator 2.4.0.2: User's Guide

noop = nothing happens

log = only log message
reap (default) = delete instance

running_deleted_instance_poll_interval
You can set:
0 = no check
>0 = period of time in seconds when the task will be executed

if the option running_deleted_instance_action is set to log or reap than

you must specify a value greater than 0 for
running_deleted_instance_poll_interval.

Maintaining a deployed environment

You can use deployment services to maintain a deployed environment in the whole
life cycle.

Starting and stopping the services in the deployment service

node
You can manage the services that run in the deployment service node.
This table illustrates how you can manage the services that run in the deployment
service node.
Table 14. Managing deployment service node services
Services

Check status

Start command

Stop command

http service

service httpd status

service httpd start

service httpd stop

chef server

/opt/chef-server/
bin/chef-server-ctl
status

/opt/chef-server/
bin/chef-server-ctl
start

/opt/chef-server/
bin/chef-server-ctl
stop

Heat

service
openstack-heat-api
status

service
openstack-heat-api
start

service
openstack-heat-api
stop

service
openstack-heatengine status

service
openstack-heatengine start

service
openstack-heatengine stop

service ds-api status

service ds-api start

service ds-api stop

service ds-engine
status

service ds-engine
start

service ds-enginestop

Deployment service

Chapter 2. Installing

143

Table 14. Managing deployment service node services (continued)

Services

Check status

Start command

Stop command

Nova

service
openstack-nova-api
status

service
openstack-nova-api
start

service
openstack-nova-api
stop

service
openstack-novaschduler status

service
openstack-novascheduler start

service
openstack-novascheduler stop

service
openstack-novanetwork status

service
openstack-novanetwork start

service
openstack-novanetwork stop

service
openstack-novaconductor status

service
openstack-novaconductor start

service
openstack-novaconductor stop

service
openstack-novacompute status

service
openstack-novacompute start

service
openstack-novacompute stop

service
openstack-glance-api
status

service
openstack-glance-api
start

service
openstack-glance-api
stop

service
openstack-glanceregistry status

service
openstack-glanceregistry start

service
openstack-glanceregistry stop

ps -ef | grep db2

su db2inst1;db2start

su db2inst1; db2stop

Glance

DB2

Scaling out a deployed environment

More nodes can be added as compute nodes after the first deployment.
Run one of the following procedures on the Deployment Server:
v Use the deployment service wizard to add new nodes to a deployed
environment. Perform the following steps:
1. Run the following command to launch the interactive CLI:
source /root/keystonerc;

ds wizard

Note: Terminal window must be at least 35 lines and 130 columns.

2. Choose the following option to modify an existing IBM Cloud Orchestrator
deployment:
[1] Modify IBM Cloud Orchestrator deployment.
- Modify an IBM Cloud Orchestrator deployment, add region server or KVM compute node.

and follow the interactive procedure by entering the required information.

For information about the deployment parameters, see Deployment
parameters on page 213.
v Use the deployment service CLI to add new nodes to a deployed environment.
Perform the following steps:
1. Check that the following jobs exist:
ds job-list
+--------------------------------------+---------------+---------| id
| name
| status
+--------------------------------------+---------------+---------| 80a8b343-8c92-4558-a18d-3b5d0836403c | centralserver | FINISHED
| d66993ee-2aa6-4182-8897-ac6a633b1959 | regionserver | FINISHED

144

IBM Cloud Orchestrator 2.4.0.2: User's Guide

+--------------------------------------+---------------+---------+--------------------------------------+----------------------------+----------------------------+
| pjob_id
| created_at
| updated_at
|
+--------------------------------------+----------------------------+----------------------------+
|
| 2014-04-16T03:07:39.567679 | 2014-04-17T05:10:22.080938 |
| 80a8b343-8c92-4558-a18d-3b5d0836403c | 2014-04-17T05:38:13.854903 | 2014-04-17T12:29:11.730405 |
+--------------------------------------+----------------------------+----------------------------+

2. Retrieve the available resource for a job. Get a list of the available resources
for a job with the following command:
source /root/keystonerc; ds job-resources-list <job_id>

For example:
ds job-resources-list d66993ee-2aa6-4182-8897-ac6a633b1959
+-------------------+------------------+-----------------------------+----------| name
| type
| run_list
| run_order
+-------------------+------------------+-----------------------------+----------| kvm_region_server | Existing Machine | role[allinone]
| 1
| compute
| Existing Machine | role[os-compute-worker-sco] | 2
+-------------------+------------------+-----------------------------+----------+--------------------------------------+
| node_id
|
+--------------------------------------+
| 921b8f28-fdad-4856-9299-4cb0b596abe7 |
| 04e73c27-1b77-4f00-9444-86f74ace54f8 |
+--------------------------------------+

3. Register more nodes. More nodes can be added as additional compute nodes.
For example:
ds node-create -t IBM::SCO::Node
-p {Address: 192.0.2.108, Port: 22, User: root, Password: passw0rd} computeB
ds node-list
+--------------------------------------+----------+----------------+-------| id
| name
| type
| status
+--------------------------------------+----------+----------------+-------| df9dba9b-fae0-46cf-a0ff-dacd736c294f | central1 | IBM::SCO::Node | INUSE
| d68bb1c7-6ca8-4d5b-a491-1e078062c1c9 | computeB | IBM::SCO::Node | FREE
| e31532bc-941d-4ffc-8f5f-3aa7cc388252 | central2 | IBM::SCO::Node | INUSE
| 921b8f28-fdad-4856-9299-4cb0b596abe7 | region | IBM::SCO::Node | INUSE
| 04e73c27-1b77-4f00-9444-86f74ace54f8 | compute | IBM::SCO::Node | INUSE
+--------------------------------------+----------+----------------+-------+--------------------------------------+-------------------+---------------------------| job_id
| resource
| created_at
+--------------------------------------+-------------------+---------------------------| 80a8b343-8c92-4558-a18d-3b5d0836403c | central_server_1 | 2014-04-16T03:03:48.641240
|
|
| 2014-04-22T07:17:36.746637
| 80a8b343-8c92-4558-a18d-3b5d0836403c | central_server_2 | 2014-04-16T03:04:08.481278
| d66993ee-2aa6-4182-8897-ac6a633b1959 | kvm_region_server | 2014-04-16T03:04:46.041518
| d66993ee-2aa6-4182-8897-ac6a633b1959 | compute
| 2014-04-16T03:05:08.254468
+--------------------------------------+-------------------+---------------------------+----------------------------+
| updated_at
|
+----------------------------+
| 2014-04-16T03:07:39.639649 |
|
|
| 2014-04-16T03:07:39.611661 |
| 2014-04-17T05:38:13.884313 |
| 2014-04-17T05:38:13.898513 |
+----------------------------+

4. Associate the nodes to the existing job by running the following command:
source /root/keystonerc; ds job-associate-node [-N <RES1=NODE1;RES2=NODE2...>] <NAME or ID>

For example:

Chapter 2. Installing

145

source /root/keystonerc;
ds job-associate-node -N compute=d68bb1c7-6ca8-4d5b-a491-1e078062c1c9
d66993ee-2aa6-4182-8897-ac6a633b1959

If you need to associate one or more nodes to a new job, you can
disassociate the node (or multiple nodes) from the current job by running the
following command:
source /root/keystonerc; ds job-disassociate-node [-N <NODE1,NODE2...>]

Optional arguments:
-N <NODE1,NODE2...>, --nodes <NODE1,NODE2...>

Removes node mapping of the deployment job. This can be specified

multiple times, or once with nodes separated by commas.
For example:
ds job-disassociate-node -N 4d591adf-c01a-42e7-8162-23cbf8ec5637,faf02217-4cc6-421e-9def-08f96b29b2b0

disassociates the specified two nodes from the deployment job.

5. Update the job by running the following command:
source /root/keystonerc; job-update <NAME or ID>

After the execution finishes, the job is marked as UPDATED. For example:
ds job-list
+--------------------------------------+---------------+---------| id
| name
| status
+--------------------------------------+---------------+---------| 80a8b343-8c92-4558-a18d-3b5d0836403c | centralserver | FINISHED
| d66993ee-2aa6-4182-8897-ac6a633b1959 | regionserver | UPDATED
+--------------------------------------+---------------+---------+--------------------------------------+----------------------------+----------------------------+
| pjob_id
| created_at
| updated_at
|
+--------------------------------------+----------------------------+----------------------------+
|
| 2014-04-16T03:07:39.567679 | 2014-04-17T05:10:22.080938 |
| 80a8b343-8c92-4558-a18d-3b5d0836403c | 2014-04-17T05:38:13.854903 | 2014-04-17T12:29:11.730405 |
+--------------------------------------+----------------------------+----------------------------+

Backing up and restoring Deployment Service

The ds-backup and ds-restore commands are provided in the Deployment Server
to backup and restore the data for Deployment Service. The ds-backup command
backs up the important data included in the database, chef data and other
important files.
To back up with the ds-backup command, run:
ds-backup <DBINSTANCENAME> <OUTPUT_LOCATION> [MODE]

where:
<DBINSTANCENAME>
Defines the instance name of DB2.
<OUTPUT_LOCATION>
Defines the backup package location, the ds-backup command will package
all files into a tag.gz file and put it into this location.
[MODE]
Defines the database backup mode, can be online or offline. This
argument can be ignored and the default value is online if ignored.

146

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: It is required to stop all of the services connected to DB2 before doing
offline backup.
Note: There are some setup steps needed to enable the online database backup.
For more information, see the DB2 documentation.
To restore with the ds-restore command:
ds-restore <DBINSTANCENAME> <BACKUP_PACKAGE>

where:
<DBINSTANCENAME>
Defines the instance name of the DB2.
<BACKUP_PACKAGE>
Defines the backup output. For example /tmp/backup/
ds20140528140442.tar.gz
Note: It is required to stop all of the services connected to DB2 before doing a
restore.

Upgrading
To upgrade IBM Cloud Orchestrator, complete these steps.
Important: Before any upgrade, create a backup of the Deployment Server and of
each IBM Cloud Orchestrator server. For example, create a snapshot of each virtual
server.
Before the upgrade, temporarily ensure that your IBM Cloud Orchestrator
passwords do not include any special characters, or the upgrade is likely to fail.
After the upgrade completes successfully, you can update the IBM Cloud
Orchestrator passwords to contain special characters.

Upgrading from SmartCloud Orchestrator V2.3 or V2.3.0.1

You can upgrade from IBM SmartCloud Orchestrator V2.3 or V2.3.0.1 to IBM
Cloud Orchestrator V2.4, V2.4.0.1, or V2.4.0.2 by using the Deployment Service
wizard or the ico-upgrade-tool command.

Before you begin

In this topic, SmartCloud Orchestrator refers to SmartCloud Orchestrator V2.3 or
V2.3.0.1, and IBM Cloud Orchestrator refers to IBM Cloud Orchestrator V2.4,
V2.4.0.1, or V2.4.0.2.
Make sure that:
v The SmartCloud Orchestrator version is V2.3 or V2.3.0.1.
v The SmartCloud Orchestrator V2.3 or V2.3.0.1 hardware fulfills the IBM Cloud
Orchestrator V2.4 hardware prerequisites, as described in Hardware
prerequisites on page 19.
v The SmartCloud Orchestrator V2.3 or V2.3.0.1 Central Servers, Region Servers,
and compute nodes (for a KVM region) are running on Red Hat Enterprise
Linux 6.4 or 6.5. For more information, see Software prerequisites on page 21.
If you must upgrade Red Hat Enterprise Linux, reboot your servers after the
upgrade procedure completes.
Chapter 2. Installing

147

v The IBM Cloud Orchestrator Deployment Service is installed and can connect to
all SmartCloud Orchestrator V2.3 Central Servers, Region Servers, and compute
nodes (for a KVM region). The version of Red Hat Enterprise Linux that is
installed on the Deployment Server must be the same as the version that is
installed on the SmartCloud Orchestrator V2.3 or V2.3.0.1 servers.
v The correct nameserver entry is configured in the /etc/resolv.conf file on the
Deployment Service server. SmartCloud Orchestrator V2.3 supports three DNS
options. If option A (built-in DNS) or option B (a built-in DNS with corporate
DNS as parent) is used, add a nameserver entry that points to Central Server 1.
If option C (corporate DNS) is used, add a nameserver entry that points to the
corporate DNS server.
v If you use Red Hat Enterprise Linux 6.5 as the operating system to host
SmartCloud Orchestrator V2.3 Central Servers, before upgrading to IBM Cloud
Orchestrator V2.4, the version of the openssl package on Central Server 3 is at
least version openssl-1.0.1e-16.el6.x86_64. Otherwise, the upgrade procedure
might fail when mapping images between the Workload Deployer component
and OpenStack.
Note: If you are using Red Hat Enterprise Linux 6.4 on the Central Servers, you
must upgrade the openssl rpm to the latest version on the Central Servers when
you will deploy Red Hat Enterprise Linux virtual machines with cloud-init. If
newer openssl agents connect to an out of date openssl server, the deployed
virtual machine gets an exception on cloud-init processing and the pattern
stays in state Preparing middleware.
v For VMware Region Server upgrade, users of vSphere 5.0 or earlier must host
their WSDL files locally. These steps are applicable for vCenter 5.0 or ESXi 5.0.
You can either mirror the WSDL from the vCenter or ESXi server that you
intend to use, or you can download the SDK directly from VMware. Refer to
section vSphere 5.0 and earlier additional set up and Procedure 2.1. To mirror
WSDL from vCenter (or ESXi) in OpenStack, see the OpenStack VMware
vSphere configuration for how to prepare WSDL files and configure
wsdl_location.
Note: Make sure that the VMware region nova user has permission to access the
folder and file configured for wsdl_location in the /etc/nova.conf file. For
upgrade from SmartCloud Orchestrator V2.3, you do not need to configure
wsdl_location in the VMware region /etc/nova.conf file. Instead, you must
configure the vmwsdlloc option in the upgrade configuration file. For more
information, see Configuring the upgrade configuration file on page 158.
v You do not install more than one IBM Cloud Orchestrator instance on the same
vCenter environment if the instances have access to the same resources. Each
IBM Cloud Orchestrator instance must use a different userid to access the
vCenter. The intersection between the resources that are seen by these users (for
example, clusters, datastore) must be empty.
v If you have IBM SmartCloud Orchestrator Content Pack for UrbanCode Deploy
installed in SmartCloud Orchestrator V2.3, you install the new version from IBM
Cloud Orchestrator before upgrading from SmartCloud Orchestrator V2.3 to IBM
Cloud Orchestrator V2.4.
Restriction: The self-service categories Virtual System Operations (Single
Instance) and Virtual System Operations (Multiple Instances) are not migrated.
These categories and related offerings are replaced with new offerings in IBM
Cloud Orchestrator V2.4. If you added your own customized offerings to either of
these categories and you want to migrate your offerings, create a new self-service
category, and move your offerings from Virtual System Operations (Single

148

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Instance) and Virtual System Operations (Multiple Instances) to your new

self-service category. You can move a self-service offering between categories by
editing the offering and changing the related category in the offering details.
Before you upgrade, complete the following steps:
1. Back up the Deployment Server, the Central Servers, the Region Servers, and
the Compute Nodes.
[VMware only:] For information about how to take snapshots of
VMware-hosted Central Servers and Region Servers, see http://
pubs.vmware.com/vsphere-50/index.jsp?topic=
%2Fcom.vmware.vsphere.vm_admin.doc_50%2FGUID-64B866EF-7636-401CA8FF-2B4584D9CA72.html.
2. Temporarily ensure that your SmartCloud Orchestrator passwords do not
include any special characters, or the upgrade is likely to fail.
During installation and upgrade, SmartCloud Orchestrator passwords can
contain only alphanumeric characters and underscores (0-9 a-z A-Z _). Spaces,
hyphens, and other special characters are not allowed. If necessary, change the
passwords to remove any special characters until after the upgrade is complete.
For instructions about how to change the passwords in SmartCloud
Orchestrator V2.3 or V2.3.0.1, see Changing the various passwords (V2.3).
It is not necessary to remove the special characters from operating system (OS)
passwords.
3. Download the image files required for the upgrade, as described in
Downloading the required image files on page 32.
[Optional] You do not have to be a root user to upgrade to IBM Cloud
Orchestrator. A nonroot user can upgrade if the user has sudo access privileges. To
configure a user with sudo access privileges, add the following line to the
/etc/sudoers file:
<user> ALL=(ALL)NOPASSWD:ALL

About this task

The upgrading procedure performs the following steps:
1. Checks the upgrade prerequisites.
2. Collects the SmartCloud Orchestrator V2.3 or V2.3.0.1 installation information
which is used for the upgrade.
3. Backs up the OpenStack configuration files. All configuration files are backed
up to /opt/ibm/openstack_backup/sco23_upgrade.
4. Upgrades DB2 on the Central Servers and the Region Servers from V10.1 to
V10.5.
5. Upgrades the IBM Cloud Orchestrator components to version 2.4, and performs
the database migration for the VMware regions.
After the upgrade, all the services remain on the same server as in SmartCloud
Orchestrator V2.3 or V2.3.0.1, with the following exceptions:
v Virtual Image Library and the iaasgateway service are stopped on Central Server
2.
v SmartCloud Orchestrator user interface is moved from Central Server 3 to
Central Server 4. For more information, see Accessing IBM Cloud Orchestrator
user interfaces on page 222.
v SmartCloud Entry service is removed from VMware region and replaced with
the new nova service.
Chapter 2. Installing

149

You can upgrade to IBM Cloud Orchestrator by running one of the following
procedures:
v Using the Deployment Service wizard to upgrade
v Using the command-line interface to upgrade on page 152

Using the Deployment Service wizard to upgrade

You can upgrade from SmartCloud Orchestrator V2.3 or V2.3.0.1 to IBM Cloud
Orchestrator V2.4, V2.4.0.1, or V2.4.0.2 by using the Deployment Service wizard.

Before you begin

In this topic, SmartCloud Orchestrator refers to SmartCloud Orchestrator V2.3 or
V2.3.0.1, and IBM Cloud Orchestrator refers to IBM Cloud Orchestrator V2.4,
V2.4.0.1, or V2.4.0.2.
Be sure you meet the prerequisites listed in Upgrading from SmartCloud
Orchestrator V2.3 or V2.3.0.1 on page 147.

About this task

To upgrade to IBM Cloud Orchestrator, perform the following steps:

Procedure
1. Start the Deployment Service wizard by running the following command on
the Deployment Server:
v For the root user:
source /root/openrc; ds wizard

v For a non-root user, create an openrc file in your home directory, and insert
the following content:
export
export
export
export
export

OS_USERNAME=admin
OS_PASSWORD=$(openstack-obfuscate -u encrypted_admin_password)
OS_TENANT_NAME=admin
OS_AUTH_URL=http://fqdn_or_ip_address_of_deployment_service_node:5000/v2.0
OS_REGION_NAME=Deployment

To run any ds command, you must first source the openrc file:
source ~/openrc;

ds wizard

The following options are displayed:

[0] New IBM Cloud Orchestrator deployment.
- Start a new IBM Cloud Orchestrator deployment.
[1] Modify IBM Cloud Orchestrator deployment.
- Modify IBM Cloud Orchestrator deployment, add region server or KVM compute node.
[2] Discover an IBM SmartCloud Orchestrator 2.3.x topology.
- Discover an IBM SmartCloud Orchestrator 2.3.x topology.
[3] Upgrade an IBM SmartCloud Orchestrator 2.3.x deployment.
- Upgrade an IBM SmartCloud Orchestrator 2.3.x deployment.
[4] Deployment job(s) status.
- Display deployment job(s) status.

2. Discover the SmartCloud Orchestrator 2.3.x topology by running the following

steps:
a. Select option [2]. The following options are displayed:
Input existing SCO 2.3.x deployment information.
==================================================
Input existing SCO 2.3.x deployment information.
[0] Input SCO2.3.X central-server1 information ...

150

IBM Cloud Orchestrator 2.4.0.2: User's Guide

[1] Input the parameters needed for SCO2.3.X upgrade ...

[2] End editing

b. Select option [0] and specify the SmartCloud Orchestrator 2.3.x Central
Server 1 information like IP address, port, user, and password or keyfile.
c. Select option [1] and specify the following parameters:
force_discover
Specify to recollect the information about SmartCloud Orchestrator
2.3.x environment if you already ran the discovery procedure.
location
Specifies the location where the upgrade configuration file is stored.
sco_admin_user
Specifies the user name of the SmartCloud Orchestrator 2.3.x
administrator.
sco_admin_password
Specifies the password of the SmartCloud Orchestrator 2.3.x
administrator.
use_extdb
Specifies if SmartCloud Orchestrator 2.3.x uses an external database.
d. Select option [2]. The discovery procedure starts.
e. When the discovery procedure completes, the following options are
displayed:
Configure upgrade configuration file for SCO2.3.X upgrade.
============================================================
Configure upgrade configuration file for SCO2.3.X upgrade.
[0] Configure central server for SCO2.3.X upgrade ...
[1] Configure region VMwareRegion for SCO2.3.X upgrade ...
[2] Configure region KVMRegion for SCO2.3.X upgrade ...
[3] End editing

Select option [0] to configure the upgrade options for Central Servers.
Select the other options to configure the upgrade options for each Region
Server.
f. Select option [3] to end the editing. The discovery procedure finished and
the following options are displayed:
[0] New IBM Cloud Orchestrator deployment.
- Start a new IBM Cloud Orchestrator deployment.
[1] Modify IBM Cloud Orchestrator deployment.
- Modify IBM Cloud Orchestrator deployment, add region server or KVM compute node.
[2] Discover an IBM SmartCloud Orchestrator 2.3.x topology.
- Discover an IBM SmartCloud Orchestrator 2.3.x topology.
[3] Upgrade an IBM SmartCloud Orchestrator 2.3.x deployment.
- Upgrade an IBM SmartCloud Orchestrator 2.3.x deployment.
[4] Deployment job(s) status.
- Display deployment job(s) status.

3. Upgrade SmartCloud Orchestrator 2.3.x by running the following steps:

a. Select option [3]. The following options are displayed:
Input existing SCO 2.3.x deployment information.
==================================================
Input existing SCO 2.3.x deployment information.
Chapter 2. Installing

151

[0] Input SCO2.3.X central-server1 information ...

[1] End editing

b. Select option [0] and specify the SmartCloud Orchestrator 2.3.x Central
Server 1 information like IP address, port, user, and password or keyfile.
c. Select option [1]. The following options are displayed:
Start Deployment
==================
Confirm to start the deployment
[0] Start the deployment.
- Start the IBM Cloud Orchestrator deployment.

d. Select option [0] to start the deployment.

e. When the upgrade job is created successfully, the following message is
displayed. For example:
Upgradation jobs was launched successfully.
Upgradation Jobs are : ( CentralServer_192_0_2_112_Upgrade, VMwareRegion_192_0_2_112_Upgrade,
KVMRegion_192_0_2_112_Upgrade ), use ds job-show <job id> to check the job status.
Press any key to continue.

Press any key to continue.

f. To check the status of the upgrade jobs, select option [4] Deployment job(s)
status. The following options are displayed, for example:
Deployment Job Status
=======================
Choose the deployment job to display.
[0] VMwareRegion_192_0_2_112_Upgrade (1c89bee8-13b2-4be8-8319-6d9d218d4a3a)
- Job status: FINISHED, updated_at: 2014-09-04T08:11:38.582142
[1] CentralServer_192_0_2_112_Upgrade (4a8ba8ad-40ec-4fd2-8bda-cda6020c131e)
- Job status: FINISHED, updated_at: 2014-09-04T07:44:44.601038
[2] KVMRegion_192_0_2_112_Upgrade (b353d49f-dc10-4c90-8f0e-dca25ca1c23a)
- Job status: FINISHED, updated_at: 2014-09-04T08:00:29.192912

Using the command-line interface to upgrade

You can upgrade from SmartCloud Orchestrator V2.3 or V2.3.0.1 to IBM Cloud
Orchestrator V2.4, V2.4.0.1, or V2.4.0.2 by using the ico-upgrade-tool command.

Before you begin

In this topic, SmartCloud Orchestrator refers to SmartCloud Orchestrator V2.3 or
V2.3.0.1, and IBM Cloud Orchestrator refers to IBM Cloud Orchestrator V2.4,
V2.4.0.1, or V2.4.0.2.
Ensure that your environment meets the prerequisites listed in Upgrading from
SmartCloud Orchestrator V2.3 or V2.3.0.1 on page 147.
Ensure that the SmartCloud Orchestrator servers are started in the following
scenarios:
v When you run the ico-upgrade-tool discover command for the first time
v When you run the ico-upgrade-tool discover command with the --force
option
In each of these scenarios, the ico-upgrade-tool command connects to the
SmartCloud Orchestrator servers and collects OpenStack information such as

152

IBM Cloud Orchestrator 2.4.0.2: User's Guide

endpoints and hypervisor lists, and runs Workload Deployer commands to collect
Workload Deployer image mappings and so on. The collected information is saved
on the Deployment Server.
You can subsequently run the ico-upgrade-tool command without the --force
option when the SmartCloud Orchestrator servers are stopped. In this case, the
saved information is read.
To force the ico-upgrade-tool command to connect to the SmartCloud
Orchestrator servers and collect information again, use the --force option:
ico-upgrade-tool discover -C SCO23_Central_Server1_IP_address
-p SCO23_Central_Server1_root_password
--admin-user SCO23_admin_user
--admin-pass SCO23_admin_password
--force
-f upgrade_config_file

About this task

Run the ico-upgrade-tool command on the Deployment Server in the IBM Cloud
Orchestrator environment. The syntax of the ico-upgrade-tool command is as
follows:
ico-upgrade-tool [--version] [--tool_version ico_upgrade_tool_version] [-d] [-v] subcommand

where subcommand is one of the following subcommands:

discover
Generates the configuration file for the upgrade.
list

Lists the topology of the last installed SmartCloud Orchestrator release.

upgrade
Upgrades SmartCloud Orchestrator to IBM Cloud Orchestrator.
help

Displays help information about the command or one of the

subcommands.

Use the ico-upgrade-tool help command to display detailed usage information

for the subcommands. For example, to show information about the upgrade
subcommand, run the following command:
ico-upgrade-tool help upgrade
Usage:
ico-upgrade-tool upgrade -C <central server 1 IP address>
[--port <central server 1 ssh port>]
[-u <central server 1 user name>]
[-p <central server 1 user password>]
[--key-file <central server 1 private ssh-key>]
Upgrade the SmartCloud Orchestrator 2.3 or 2.3.0.1 to IBM Cloud
Orchestrator 2.4.
Optional arguments:
-C <Central Server 1 IP address>, -- central-srv 1 < Central Server 1 IP address>
The IP address of Central Server 1.
--port <Central Server 1 ssh port>
The ssh port of Central Server 1.
-u <Central Server 1 user name>, --user <Central Server 1 user name >
The user name on Central Server 1.

Chapter 2. Installing

153

-p <Central Server 1 user password>, -- password <Central Server 1 user password>

The password of the user on Central Server 1.
--key-file <Central Server 1 private ssh-key>
The private ssh-key on Central Server 1.

To upgrade to IBM Cloud Orchestrator, complete the following steps:

Procedure
1. Back up the Central Server and Region Server virtual machines and the
Compute Nodes.
For VMware-hosted Central and Region Servers, see Taking Snapshots
(VMware) to take snapshots for Central Servers and Region Servers.
2. Run the following commands on the Deployment Server to discover the
SmartCloud Orchestrator topology and generate the upgrade configuration file
to be used by the upgrade procedure:
source /root/openrc
ico-upgrade-tool discover -C CENTRAL_SRV1_IP -p CENTRAL_SRV1_ROOT_PASS
--admin-user SCO23_ADMIN_USER
--admin-pass SCO23_ADMIN_PASSWORD
-f UPGRADE_CFG_FILE

where:
CENTRAL_SRV1_IP
Specifies the IP address of Central Server 1.
CENTRAL_SRV1_ROOT_PASS
Specifies the root password of Central Server 1.
SCO23_ADMIN_USER
Specifies the user name of the SmartCloud Orchestrator admin user.
SCO23_ADMIN_PASSWORD
Specifies the user password of the SmartCloud Orchestrator admin
user.
UPGRADE_CFG_FILE
Specifies the file where all the discovered details of a SmartCloud
Orchestrator system are written to.
Note: If SmartCloud Orchestrator uses an external database, run the
ico-upgrade-tool discover command with the --extdb option:
ico-upgrade-tool discover -C CENTRAL_SRV1_IP -p CENTRAL_SRV1_ROOT_PASS
--admin-user SCO23_ADMIN_USER
--admin-pass SCO23_ADMIN_PASSWORD
--extdb -f UPGRADE_CFG_FILE

If you run the ico-upgrade-tool discover command again, it just reads the
saved information. In this case, you do not need to have SmartCloud
Orchestrator started. If you want to force discovery to collect the information
again, connect to the SmartCloud Orchestrator server and run the command
with the --force option.
ico-upgrade-tool discover -C YOUR_SCO23_CS1_ADDR -p PASSWORD
--admin-user SCO23_ADMIN_USER
--admin-pass SCO23_ADMIN_PASSWORD --force
-f UPGRADE_CFG_FILE

Note: Be sure that the SmartCloud Orchestrator servers are started when you
run the ico-upgrade-tool discover for the first time or when you specify the
--force option.

154

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. If all SmartCloud Orchestrator servers are running on Red Hat Enterprise

Linux 6.4 or 6.5, go to step 5 directly, otherwise, upgrade all SmartCloud
Orchestrator servers to Red Hat Enterprise Linux 6.4 or 6.5. Make sure that
your SmartCloud Orchestrator Central Servers, Region Servers, and compute
nodes (if you have a KVM region) are running on Red Hat Enterprise Linux
6.4 or 6.5. If not, upgrade your Red Hat to Red Hat Enterprise Linux 6.4 or
6.5. For more information, see https://access.redhat.com/documentation/enUS/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/ch-yum.html#s1yum-upgrade-system. After Red Hat server is upgraded, remove from
/etc/fstab the auto mount item for the old Red Hat ISO file, for example, if
SmartCloud Orchestrator servers are running on Red Hat Enterprise Linux 6.3,
remove following items from /etc/fstab:
/opt/RHEL6.3-20120613.2-Server-x86_64-DVD1.iso /data/repos/rhel6

iso9660 loop

4. Reboot your servers after the Red Hat system upgrade. If you have upgraded
your Red Hat system according to step 3, reboot your servers to make the
new Linux kernel work.
5. See Configuring the upgrade configuration file on page 158 for information
about how to configure the upgrade configuration file.
6. Stop the SmartCloud Orchestrator processes.
If System Automation Application Manager is not used to control SmartCloud
Orchestrator, see http://www-01.ibm.com/support/knowledgecenter/
SS4KMC_2.3.0/com.ibm.sco.doc_2.3/t_start_stop_sco.html to start or stop
SmartCloud Orchestrator.
If System Automation Application Manager is used to control SmartCloud
Orchestrator, see http://www-01.ibm.com/support/knowledgecenter/
SS4KMC_2.3.0/com.ibm.sco.doc_2.3/t_control_mgmt_stack.html to request
offline SmartCloud Orchestrator from System Automation Application
Manager.
7. To upgrade SmartCloud Orchestrator to IBM Cloud Orchestrator, run the
following commands on the Deployment Server:
source /root/openrc
ico-upgrade-tool upgrade -C CENTRAL_SRV1_IP -p CENTRAL_SRV1_ROOT_PASS

where:
CENTRAL_SRV1_IP
Defines the IP address of Central Server 1.
CENTRAL_SRV1_ROOT_PASS
Defines the root password of Central Server 1.
8. For VMware region upgrade, if you are using a datastore cluster or resource
pool on your VMware region managed to vCenter, see Advanced post
configuration after a VMware region is upgraded on page 168.
9. The ico-upgrade-tool command creates deployment service jobs for the
upgrade. Wait until the status of all the upgrade jobs is FINISHED.
After the upgrade, the SmartCloud Orchestrator OpenStack configuration files
are overwritten with the IBM Cloud Orchestrator configurations. The
customized configuration in SmartCloud Orchestrator, for example, the LDAP
configuration, must be merged back manually. All the SmartCloud
Orchestrator OpenStack configuration files are backed up to
/opt/ibm/openstack_backup/sco23_upgrade/. For example, the keystone
configuration files are backed up to /opt/ibm/openstack_backup/
sco23_upgrade/keystone on Central Server 2.

Chapter 2. Installing

155

0 0

After the configuration files are merged back, the corresponding service must
be restarted. For example, after the LDAP configuration files are merged back,
run the /etc/init.d/openstack-keystone restart command to restart the
keystone service.
10. If System Automation Application Manager is used to control IBM Cloud
Orchestrator, reconfigure System Automation Application Manager by
following the procedure described in http://www-01.ibm.com/support/
knowledgecenter/SS4KMC_2.3.0/com.ibm.sco.doc_2.3/t_conf_saappman.html.
Re-configure service autostart on the Central Servers, Region Servers, and
Compute Nodes, and re-execute the step to copy control scripts from
/iaas/scorchestrator to /home/saam on all the servers.

What to do next
The ico-upgrade-tool exits when the upgrade jobs for Central Servers and Region
Servers are executed. The tool does not report failure or success status of the job.
To check if the upgrade for SmartCloud Orchestrator has completed, use the
following commands on the Deployment Server:
source /root/openrc
ds job-list

You can see the status of Central Servers upgrade from job
CentralServer_CS1_SUFFIX_Upgrade status, see the status of region servers upgrade
from job YOUR_REGION_NAME_CS1_SUFFIX_Upgrade status, for example, if your region
name is VmwareRegion, Central Server IP is 192.0.2.192, then your job name is
VmwareRegion_192_0_2_192_Upgrade.
To see the job details, use following command:
ds job-show JOB_ID

where JOB_ID is the job ID of the Central Server or Region Server upgrade job.
If the upgrade finished successfully, the status of all the upgrade jobs is FINISHED.
If an upgrade job failed with status ERROR, refer to the var/log/ds/ds-engine.log
file on the Deployment Server for details.
If the upgrade failed, you can roll back your IBM Cloud Orchestrator environment
with the data backed up.
For VMware-hosted Central and Region Servers, to restore Central Servers and
Region Servers, see http://pubs.vmware.com/vsphere-51/topic/
com.vmware.vsphere.vm_admin.doc/GUID-E0080795-C2F0-4F05-907C2F976433AC0D.html.
For KVM hosted Central and Region Servers, to restore Central Servers and Region
Servers, see http://www-01.ibm.com/support/knowledgecenter/SS4KMC_2.3.0/
com.ibm.sco.doc_2.3/t_backup_services.html.
Note:
v The opt/ibm/orchestrator/SCOrchestrator.py script (moved from the
/iaas/scorchestrator directory in SmartCloud Orchestrator to the
/opt/ibm/orchestrator directory in IBM Cloud Orchestrator) on Central Server 1
can be used to check the status of services after an upgrade. The status of each
service is shown below in the output from the script. Some of the services have

156

IBM Cloud Orchestrator 2.4.0.2: User's Guide

changed in IBM Cloud Orchestrator. These services will now show a status of
offline and should not be started. The services which are disabled after an
upgrade are as follows:
"openstack-nova-metadata-api" on a KVM compute node.
"openstack-nova-compute" and "openstack-nova-network" on a VMware
region
For a VMware region upgrade, the compute and network services are named
openstack-nova-compute-CLUSTER_NAME and openstack-nova-networkCLUSTER_NAME instead.
[root@cs-144-1 scorchestrator]# ./SCOrchestrator.py status
Environment in : /opt/ibm/orchestrator/scorchestrator/SCOEnvironment.xml
Cloud topology refreshed successfully to file:
/opt/ibm/orchestrator/scorchestrator/SCOEnvironment_fulltopo.xml
===>>> Collecting Status for SmartCloud Orchestrator
===>>> Please wait ======>>>>>>
Component
Hostname
Status
-----------------------------------------------------------------IHS
172.16.144.204
online
bpm-dmgr
172.16.144.204
online
bpm-node
172.16.144.204
online
bpm-server
172.16.144.204
online
httpd
172.16.144.204
online
iwd
172.16.144.203
online
openstack-cinder-api
172.16.144.206
online
openstack-cinder-api
172.16.144.205
online
openstack-cinder-scheduler
172.16.144.206
online
openstack-cinder-scheduler
172.16.144.205
online
openstack-cinder-volume
172.16.144.206
online
openstack-cinder-volume
172.16.144.205
online
openstack-glance-api
172.16.144.206
online
openstack-glance-api
172.16.144.205
online
openstack-glance-registry
172.16.144.206
online
openstack-glance-registry
172.16.144.205
online
openstack-heat-api
172.16.144.206
online
openstack-heat-api
172.16.144.205
online
openstack-heat-api-cfn
172.16.144.206
online
openstack-heat-api-cfn
172.16.144.205
online
openstack-heat-api-cloudwatch 172.16.144.206
online
openstack-heat-api-cloudwatch 172.16.144.205
online
openstack-heat-engine
172.16.144.206
online
openstack-heat-engine
172.16.144.205
online
openstack-keystone
172.16.144.202
online
openstack-nova-api
172.16.144.206
online
openstack-nova-api
172.16.144.205
online
openstack-nova-cert
172.16.144.206
online
openstack-nova-cert
172.16.144.205
online
openstack-nova-compute
172.16.52.20
online
openstack-nova-compute
172.16.144.205
offline
openstack-nova-conductor
172.16.144.206
online
openstack-nova-conductor
172.16.144.205
online
openstack-nova-metadata-api
172.16.52.20
offline
openstack-nova-metadata-api
172.16.144.206
online
openstack-nova-metadata-api
172.16.144.205
online
openstack-nova-network
172.16.52.20
online
openstack-nova-network
172.16.144.205
offline
openstack-nova-novncproxy
172.16.144.206
online
openstack-nova-novncproxy
172.16.144.205
online
openstack-nova-scheduler
172.16.144.206
online
openstack-nova-scheduler
172.16.144.205
online
pcg
172.16.144.202
online
qpidd
172.16.144.201
online
qpidd
172.16.144.206
online
qpidd
172.16.144.205
online
Chapter 2. Installing

157

swi

172.16.144.204

online

===>>> Status SmartCloud Orchestrator complete

Upgrading with an external database

You can upgrade from SmartCloud Orchestrator V2.3 or V2.3.0.1 with an external
database to IBM Cloud Orchestrator V2.4, V2.4.0.1, or V2.4.0.2. You must manually
upgrade the external database to DB2 V10.5 and manually configure the VMware
region if it is installed.

Before you begin

In this topic, SmartCloud Orchestrator refers to SmartCloud Orchestrator V2.3 or
V2.3.0.1, and IBM Cloud Orchestrator refers to IBM Cloud Orchestrator V2.4,
V2.4.0.1, or V2.4.0.2.

Procedure
1. Upgrade the external database to DB2 V10.5 manually. See the information
about upgrading DB2 manually in the IBM Knowledge Center at
http://www-01.ibm.com/support/docview.wss?uid=swg21633449.
2. There are new OpenStack components added to IBM Cloud Orchestrator V2.4.
For Central Servers, OpenStack horizon or ceilometer newly added to Central
Server 4 in IBM Cloud Orchestrator V2.4. perform the following steps on the
database server:
a. Create a DB2 database for OpenStack horizon and ceilometer or use the
same DB2 database as in the other OpenStack components.
b. Create a DB2 user for OpenStack horizon and ceilometer.
For each Region Server, OpenStack heat or ceilometer newly added to Region
Servers in IBM Cloud Orchestrator V2.4, perform the following steps on the
database server
a. Create a DB2 database for OpenStack heat and ceilometer or use the same
db2 database as in the other OpenStack components.
b. Create a DB2 user for OpenStack heat and ceilometer.
3. Upgrade SmartCloud Orchestrator V2.3 to IBM Cloud Orchestrator V2.4 with
the command ico-upgrade-tool. For information about upgrading, see
Upgrading from SmartCloud Orchestrator V2.3 or V2.3.0.1 on page 147.
4. The KVM region is upgraded automatically after step 2. For the VMware
region, manually migrate the VMware Region database after step 2 is
completed. For more information, see Migrating data in a VMware region on
page 164.

Configuring the upgrade configuration file

The ico-upgrade-tool collects information from the SmartCloud Orchestrator V2.3
environment and saves it to the upgrade configuration file you specify when you
run the ico-upgrade-tool discover command.

About this task

The configuration file is saved in JSON format. Make sure that after you edit this
file, it can still be parsed as a valid JSON file.
Configurations are generated for Central Servers with the item named as
centralserver, and for each region server with the item named as region name, for

158

IBM Cloud Orchestrator 2.4.0.2: User's Guide

example, centralserver part is for all central servers, KVMRegion part is for the
KVM region, and VMwareRegion part is for the VMware region.
Most of the options are generated with the values collected from SmartCloud
Orchestrator V2.3 except what you must do in the following procedure.

Procedure
1. Make sure that no option values in the upgrade configuration file are empty.
Note: If your SmartCloud Orchestrator V2.3 environment uses corporate DNS,
the SingleSignOnDomain entry in the upgrade configuration file is empty. You
must set the SingleSignOnDomain parameter value to the DNS domain name
where the manage-from components are installed. For more information about
the SingleSignOnDomain parameter, see Customizing deployment parameters
on page 37.
Note: If your VMware region servers are connected to vCenter later than 5.0,
the vmwsdlloc option must be empty.
2. For VMware region server, the following parameters are mandatory for the
vCcenter configuration:
VMWareRegion: {
.......
"vcenter": {
......
"password": "",
"user": "",
"vminterface": ""
}
"vmdatastore": ""

# Vcenter users password

# Vcenter users name
# Physical Adapter on ESXi server(such as vmnic0 or vmnic1..)
# VMware datastore name

.......
}

vmdatastore is a parameter which when set configures Nova by setting the

value to the datastore_regex configuration item in /etc/nova/nova.conf file.
The datastore_regex setting specifies the data stores to use with Compute.
This setting uses regular expressions. For example, datastore_regex="nas.*"
selects all the data stores that have a name starting with nas. For example,
datastore_regex="datastore001|datastore002|datastore003" selects
"datastore001" or "datastore002" or "datastore003". If this line is omitted,
Compute uses the first data store returned by the vSphere API. Refer to:
http://docs.openstack.org/juno/config-reference/content/vmware.html.
When your VMware region servers are connected to vCenter 5.0, besides the
above mandatory parameters, vmwsdlloc is also mandatory. Follow the steps
here to configure vmwsdlloc:
a. Refer to http://docs.openstack.org/trunk/config-reference/content/
vmware.html for how to prepare WSDL files and configure
option wsdl_location.
b. Make sure region server's nova user has access to the WSDL files on either
VMware region server itself or a http server.
c. For SmartCloud Orchestrator 2.3 upgrade, we do not need to configure the
VMware region's /etc/nova.conf directly, instead, we should configure
the vmwsdllocoption in upgrade configuration file for VMware region
servers.
Chapter 2. Installing

159

d. Make sure the vmwsdlloc value starts with file:// if the WSDL files are
stored on VMware region server locally. If the WSDL files are stored on a
http server, the vmwsdlloc value should start with http://.
.
Make sure that the vCenter user name and password are correct. The vCenter
credentials can be validated in either of the following ways:
a. Login to the vSphere Web Client with the user and password, check
whether the credential can be authorized successfully.
b. In SmartCloud Orchestrator 2.3, there is a method to validate vCenter
credentials from the VMware region. For details refer to the documentation
at: http://www-01.ibm.com/support/knowledgecenter/SS4KMC_2.3.0/
com.ibm.sco.doc_2.3/t_config_sco_vmware.html?lang=en . For example:
# /opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-pingtest 192.0.2.11 admin passw0rd VMware
{"cloud": {"driver":"", "name":"", "description":"OpenStack managed VMware", \
"hostname":"192.0.2.11", "username":"scoadmin10", "password":"object00X", \
"type":"VMware", "port":443} }
{"results": {"status": "Cloud is OK and ready to deploy instances.", "id": "OK", "label": "OK"}}
# /opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-pingtest 192.0.2.11 admin wrongpass VMware
{"cloud": {"driver":"", "name":"", "description":"OpenStack managed VMware", \
"hostname":"192.0.2.11", "username":"scoadmin10", "password":"object0X", \
"type":"VMware", "port":443} }
{"results": {"status": "Unreachable Cloud: Login Failed. The user and password combination \
is invalid.", "id": "UNREACHABLE", "label": "Unreachable"}}

3. For the KVM region server, the compute node's password is mandatory. All
compute nodes for the KVM region are under the computenodes item. The
item name for compute nodes are named as the compute node's host name, for
example, for a KVM region KVMRegion with compute node
scotest-d20-compute, the configuration file looks like this:
KVMRegion: {
......
"computenodes": {
"scotest-d20-compute": {
"password": "passw0rd"
}

# All computes for kvm region are put under this item
# compute nodes hostname

......
}

4. For the options with default values, only modify them if they have been
manually changed after SmartCloud Orchestrator V2.3 was installed. These
options must be modified with the new values. For example, if the nova
database user's password has been changed after the SmartCloud Orchestrator
V2.3 installation, you must modify it with the new password. All plain text
passwords in the upgrade configuration file are encrypted after you run the
ico-upgrade-tool upgrade command.
5. External database configuration
If an external database is used for SmartCloud Orchestrator V2.3, for each
central and region service, an addition option for database IP address is
created. There is no default value for database configuration options, for
example:
"image": {
"db": {
"name": "" ,
"user": "",

160

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"address": ""
},
"servicepassword": "passw0rd"
}

All options with no default value must be input with a valid value.

Example
Sample upgrade configuration file
Here is an example of a sample upgrade configuration file. The comments after #
are not included in the configuration file:
{
"KVMRegion": {
"compute": {
"db": {
"name": "openstac",
"user": "noa54773"
},
"servicepassword": "passw0rd"
},
"computenodes": {
"scotest-d20-compute": {
"password": "passw0rd"
}
},
"image": {
"db": {
"name": "openstac",
"user": "gle54773"
},
"servicepassword": "passw0rd"
},
"metering": {
"db": {
"name": "openstac",
"user": "cel54773"
},
"servicepassword": "passw0rd"
},
"network": {
"db": {
"name": "openstac",
"user": "neu54773"
},
"servicepassword": "passw0rd"
},
"orchestration": {
"db": {
"name": "openstac",
"user": "het54773"
},
"servicepassword": "passw0rd"
},
"osdbpassword": "passw0rd",
"osdbport": "50000",
"regionname": "KVMRegion",
"smartcloudpassword": "passw0rd",
"template": "kvm_region_upgrade",
"volume": {
"db": {
"name": "openstac",
"user": "cir54773"

# nova configuration
# nova db name
# nova db user
# nova service users password
# KVMRegions compute nodes list
# compute node hostname
# compute nodes password
# glance configuration

# ceilometer configuration

# neutron configuration

# heat configuration

#
#
#
#
#

openstack database password

openstack database port
KVM regions region name
DB2 instance password
The template used for ds job

Chapter 2. Installing

161

},
"servicepassword": "passw0rd"
}
},
"VMWareRegion": {
"compute": {
"db": {
"name": "openstac",
"user": "noa20918"
},
"servicepassword": "passw0rd"
},
"image": {
"db": {
"name": "openstac",
"user": "gle20918"
},
"servicepassword": "passw0rd"
},
"metering": {
"db": {
"name": "openstac",
"user": "cel20918"
},
"servicepassword": "passw0rd"
},
"network": {
"db": {
"name": "openstac",
"user": "neu20918"
},
"servicepassword": "passw0rd"
},
"orchestration": {
"db": {
"name": "openstac",
"user": "het20918"
},
"servicepassword": "passw0rd"
},
"osdbpassword": "passw0rd",
"osdbport": "50000",
"regionname": "VMWareRegion",
"smartcloud": {
"db": {
"password": "passw0rd",
"user": "sce20918"
},
"vcenter": {
"clusters": "Cluster1",
"host": "192.0.2.11",
"password": "",
"user": "",
"vminterface": ""
}
},
"smartcloudpassword": "passw0rd",
"template": "vmware_region_upgrade_db2",
"volume": {
"db": {
"name": "openstac",
"user": "cir20918"
},
"servicepassword": "passw0rd"
}
},
"centralserver": {

162

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"BrowserSimpleTokenSecret": "rad/M4P8/MIVFGJewQagLw==",
"SimpleTokenSecret": "8oG7vheB1vwyDgxPul7uzw==",
"bpm": {
"db": {
"name": "BPMDB",
"password": "passw0rd",
"port": "50000",
"user": "bpmuser"
}
},
"cmn": {
"db": {
"name": "CMNDB",
"password": "passw0rd",
"port": "50000",
"user": "bpmuser"
}
},
"dashboard": {
"db": {
"name": "openstac",
"port": "50000",
"user": "dash"
}
},
"db2": {
"das": {
"password": "passw0rd"
},
"fenced": {
"password": "passw0rd"
},
"instance": {
"password": "passw0rd"
}
},
"keystone": {
"adminpassword": "passw0rd",
"admintoken": "c7778550072374148e7e",
"adminuser": "admin",
"db": {
"name": "openstac",
"port": "50000",
"user": "ksdb"
}
},
"metering": {
"db": {
"name": "openstac",
"port": "50000",
"user": "ceil"
}
},
"osdbpassword": "passw0rd",
"osdbport": "50000",
"pdw": {
"db": {
"name": "PDWDB",
"password": "passw0rd",
"port": "50000",
"user": "bpmuser"
}
},
"regionname": "Master",
"scui": {
"SingleSignOnDomain": "sso.mycompany.com"
},
Chapter 2. Installing

163

"smartcloudpassword": "passw0rd",
"template": "central_server_upgrade"
}
}

Requirements for upgrading a VMware Region

There are some requirements for upgrading a VMware Region from SmartCloud
Orchestrator V2.3.x to IBM Cloud Orchestrator V2.4.

About this task

SmartCloud Orchestrator V2.3.x supports an EXSI under the vCenter (DataCenter)
directly, but IBM Cloud Orchestrator V2.4 only support clusters under the vCenter
(DataCenter) officially. This means that IBM Cloud Orchestrator V2.4 only
discovers a cluster as its hypervisor. Then all EXSIs must be under some clusters in
vCenter if you want to upgrade a VMware region from SmartCloud Orchestrator
V2.3.x to IBM Cloud Orchestrator V2.4.

Procedure
1. Create clusters in vCenter.
2. Move all EXSIs which are not under clusters to a certain cluster.
3. Wait a few minutes for the synchronization from vCenter to SmartCloud
Orchestrator V2.3.x.
4. Upgrade the VMware Region.
5. Manually migrate these virtual machines which are under the EXSIs.

Migrating data in a VMware region

In SmartCloud Orchestrator V2.3, you can use an sce driver to manage VMware.
In IBM Cloud Orchestrator V2.4 an OpenStack native driver replaces it. There is a
ds upgrade tool to upgrade the VMware region from SmartCloud Orchestrator
V2.3 to IBM Cloud Orchestrator V2.4. However, in some cases, you must perform
some manual work to migrate the data.

Procedure
1. Migrate the Availability Zone:
a. Discover the Availability Zone in your Region node:
nova availability-zone-list
+-----------------------------+----------------------------------------+
| Name
| Status
|
+-----------------------------+----------------------------------------+
| internal
| available
|
| |- scotest-d20-region1
|
|
| | |- nova-cert
| enabled :-) 2014-07-19T02:21:49.041585 |
| | |- nova-conductor
| enabled :-) 2014-07-19T02:21:45.707118 |
| | |- nova-consoleauth
| enabled :-) 2014-07-19T02:21:40.908027 |
| | |- nova-network
| enabled :-) 2014-07-19T02:21:40.510854 |
| | |- nova-scheduler
| enabled :-) 2014-07-19T02:21:46.600970 |
| | |- nova-smartcloud
| enabled :-) 2014-07-19T02:21:44.159949 |
| [email protected]
| available
|
| |- [email protected] |
|
| | |- nova-compute
| enabled :-) 2014-07-19T02:21:44.171048 |
+-----------------------------+----------------------------------------+

There are two Availability Zones: internal and [email protected].

The later includes a service nova-compute, and then it is the Availability

164

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Zone that manages your virtual machines (these virtual machines that are
under the cluster cluster1 in vCenter).
Note: There might be more than one Availability Zones that manage some
virtual machines in your Region. Each of them are in format
cluster_name@vCenter_ip. Each Availability Zone "cluster_name@vCenter_ip
manage these virtual machines that are under the cluster_name in vCenter.
You can check it in vCenter.
2. Create new configuration files for the Availability Zones:
You can create new configuration files by copying your /etc/nova/nova.config.
Take the result of Step 1 as an example:
cp /etc/nova/nova.config /etc/nova/nova_cluster1_192.0.2.11.conf

Then edit the /etc/nova/nova.config /etc/nova/

nova_cluster1_192.0.2.11.conf. You can run the following commands:
openstack-config --set /etc/nova/nova_cluster1_192.0.2.11.conf \
DEFAULT default_availability_zone [email protected]
openstack-config --set /etc/nova/nova_cluster1_192.0.2.11.conf \
DEFAULT default_schedule_zone [email protected]
openstack-config --set /etc/nova/nova_cluster1_192.0.2.11.conf \
DEFAULT storage_availability_zone [email protected]
openstack-config --set /etc/nova/nova_cluster1_192.0.2.11.conf \
DEFAULT host [email protected]
openstack-config --del /etc/nova/nova_cluster1_192.0.2.11.conf vmware cluster_name
openstack-config --set /etc/nova/nova_cluster1_192.0.2.11.conf vmware cluster_name Cluster1
openstack-config --set /etc/nova/nova_cluster1_192.0.2.11.conf vmware host_ip 192.0.2.11

3. Create new service files for the Availability Zones:

You can create new configuration files by copying your /etc/init.d/
openstack-nova-compute. For example:
cp /etc/init.d/openstack-nova-compute /etc/init.d/openstack-nova-compute-Cluster1-192.0.2.11

Then apply the configuration file created in Step 2, by changing:

config="/etc/nova/nova.conf" to config="/etc/nova/nova_cluster1_192.0.2.11.conf"

4. Start your created service files:

service openstack-nova-compute-Cluster1-192.0.2.11 start

5. Clean the hypervisor:

a. Find the hypervisors:
[root@scotest-d20-region1 init.d]# nova hypervisor-list
+----+--------------------------+
| ID | Hypervisor hostname
|
+----+--------------------------+
| 1 | [email protected] |
| 21 | domain-c7(Cluster1)
|
| 22 | domain-c7(Cluster1)
|
+----+--------------------------+

The [email protected] is the original hypervisor name in

SmartCloud Orchestrator V2.3. The domain-c7(Cluster1) with id 21 is
created by openstack-nova-compute, it belongs to the default Availability
Zone nova. The domain-c7(Cluster1) with id 22 is created by your created
/etc/init.d/openstack-nova-compute-Cluster1-192.0.2.11, it belongs to
the created Availability Zone [email protected]. The hypervisor
name with id 1 and 2 must be deleted and the hypervisor name with id 22
must change its id to 1 (the original id).
Go to the DB2 server:

Chapter 2. Installing

165

db2 "delete db_username.compute_nodes where id=1"

db2 "update db_username.compute_nodes set id=1 where id=22"
db2 ""delete db_username.compute_nodes where hypervisor_hostname=domain-c7(Cluster1) and id!=1"

b. Migrate the instance:

For a certain instance, you must know which cluster it belongs to. You can
check it by running the nova show command. If its properties such as
Availability Zone, hypervisor_name are in the format of
cluster_name@vCenter it belongs to the cluster of cluster_name. If it
originally belongs to an EXSI which is not in a cluster, you must create a
cluster and move the EXSI into it (in SmartCloud Orchestrator V2.3 phrase).
In IBM Cloud Orchestrator V2.4, you might need to migrate the date
manually. For example, an instance belongs to cluster Cluster1 in the
vCenter 192.0.2.11, you must change its properties in the DB2 server. Go
to the DB2 server:
db2 "update db_username.instances set node=domain-c7(Cluster1), vm_state=active,
[email protected] where uuid=instance_uuid"

Note: You can find the value of node by running the nova hypervisor-list
command. The item that contains the cluster name is the one that you want.
c. Migrate the template:
Go to DB2 server and create the file:
/home/db2inst1/vmware_template_data_migration.sql:

Connect to OpenStack:
export to /home/db2inst1/template_data_migration-20140718134138.backup of DEL \
lobfile template_data_migration-20140718134138.lob modified by lobsinfile \
select * from gle20918.IMAGE_PROPERTIES
merge into gle20918."IMAGE_PROPERTIES" prop \
using (select id as image_id, template_name as name_key, name as name_value, deleted \
from (select distinct id, name, deleted from gle20918."IMAGES" \
where status in (active, deleted))) image \
on prop.image_id = image.image_id and prop.name = image.name_key \
when not matched \
then insert (image_id, name, "value", created_at, deleted) values \
(image.image_id, image.name_key, image.name_value, current timestamp, image.deleted)

Then run the following command:

su - db2inst1 -c db2 -w- -v -v /home/db2inst1/vmware_template_data_migration.sql

d. Migrate the network:

Go to the DB2 Server and create the file:
/home/db2inst1/nova_network_migration.sql:
Connect to OpenStack.
export to /home/db2inst1/nova_network_migration-20140718134138.backupof DEL \
LOBFILE network_lobs select * from noa20918.NETWORKS.merge into noa20918.NETWORKS nova
using (select "networkName" as netname, "osNetworkId" as netid \
from sce20918.NETWORK_EXTENSIONS) sce \
on nova.uuid = sce.netid \
when matched then \
update set nova."label"=sce.netname

Then run the command:

su - db2inst1 -c db2 -w- -v -v /home/db2inst1/nova_network_migration.sql

166

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Post-upgrade configuration
After you upgrade to IBM Cloud Orchestrator V2.4, complete any necessary
post-upgrade configuration steps.
After the upgrade, VMware discovery is not started and is not configured
automatically. If you would like to use VMware discovery, you must configure and
start it as described in Configuring vmware-discovery on page 114 and
Configuring vmware-discovery for multiple vCenters on page 116.
After the upgrade, disable the SSLv3 protocol as described in Disabling SSLv3
protocol in deployed instances on page 180.
To identify other necessary post-upgrade configuration tasks, and for information
about how to configure V2.4 features, review the topics in the Post-installation
tasks on page 72 section.

Upgrading from SmartCloud Cost Management 2.1.0.3

You can upgrade from SmartCloud Cost Management 2.1.0.3 to SmartCloud Cost
Management 2.1.0.4 by using the sccm_install.sh script. The upgrade is provided
as a console mode upgrade only.

Before you begin

Ensure that the system that you are upgrading is the same system where
SmartCloud Cost Management 2.1.0.3 has been installed. SmartCloud Orchestrator
2.3 or 2.3.0.1 must be successfully upgraded to IBM Cloud Orchestrator 2.4. The
properties defined in the sccm_install.properties file during the installation of
SmartCloud Cost Management 2.1.0.3 must also be used for the 2.1.0.4 upgrade.
These properties include:
INSTALL_DIR
The installation directory of SmartCloud Cost Management. This directory
must be the same as that used in 2.1.0.3 as the sccm_install.sh script will
use this to detect if there is a previous install and therefore if it needs to
run in upgrade mode.
ADMIN_USER
The SmartCloud Cost Management administration user.
ADMIN_PASSWORD
The SmartCloud Cost Management administration password.
HTTPS_PORT
The https port which should be used by SmartCloud Cost Management.
Note: The HTTP_PORT property is no longer present in 2.1.0.4 as SmartCloud
Cost Management can now only be configured to use https.
Note: Once SmartCloud Orchestrator 2.3 has been upgraded to IBM Cloud
Orchestrator 2.4, the SmartCloud Cost Management 2.1.0.4 upgrade should happen
immediately afterwards to prevent the loss of any metering records.

Procedure
1. Log in to the system using the login credentials required for installing on a
Linux platform .
2. Enter one of the following commands:
v ./sccm_install.sh
Chapter 2. Installing

167

v ./sccm_install.sh sccm_install.properties
Note: The sccm_install.properties file can be modified as required but must
match the parameters used in the 2.1.0.3 install.
3. Follow the directions presented on the screen to complete the installation.
4. Launch the browser: https://<host>:<port>/Blaze/Console. For example,
https://<servername>:9443/Blaze/Console.
5. Once installation is successfully completed, run the automated post-installation
configuration to ensure that SmartCloud Cost Management is configured to
work with IBM Cloud Orchestrator 2.4.
Note: Metering and Billing will not work correctly for an upgraded IBM Cloud
Orchestrator 2.4 environment unless configured correctly to do so.
Note: If you have modified job files that refer to the 2.1.0.3 default Database
datasource, after running the automated post-installation configuration process,
you must change the name of the datasource in these job files to the new
datasource name used in 2.1.0.4. The name of the default Database datasource
in 2.1.0.3 is sco_db2 and in 2.1.0.4 is ico_db2.

Post configuration after Public Cloud Gateway is upgraded

Perform the following task after Public Cloud Gateway is upgraded.
During an upgrade from SmartCloud Orchestrator 2.3 to IBM Cloud Orchestrator
2.4, the Public Cloud Gateway configuration file flavors.json (located by default
in /opt/ibm/pcg/etc) is updated. Any preexisting version of the file is backed up
and stored in the flavors.json.bak file in the same directory. The backup file can
be used to retain any changes you made to the original file.
If you change the flavors.json file, you must restart the Public Cloud Gateway by
running the following command:
service pcg restart

Advanced post configuration after a VMware region is upgraded

If you are using datastore clusters or resource pools on your VMware region
managed to vCenter, perform the following procedure to configure your VMware
region after upgrading from SmartCloud Orchestrator 2.3.

About this task

In the following procedure, Cluster1 is a cluster on vCenter, and ResourcePool1 is
a resource pool under this cluster.
Note:
v If you have multiple clusters and resource pools, you must perform the
following procedure for each of them.
v If you are using both datastore cluster and resource pool, perform all the steps
of the following procedure.
v If you are using only datastore cluster, perform steps 2, 4, and 7 of the following
procedure.
v If you are using only resource pool, perform the following procedure by
skipping step 2.

168

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. Run the following command to get a list of existing hypervisors and record the
related hypervisor IDs, because the original hypervisor is deleted by the nova
compute after the manual configuration and after restarting the nova
compute service.
nova hypervisor-list
+-----+-----------------------------------------------------+
| ID | Hypervisor hostname
|
+-----+-----------------------------------------------------+
| 101 | domain-c27(Cluster1)
|
| 102 | resgroup-87(ResourcePool1)
|
+----+------------------------------------------------------+

2. Configure the datastore cluster:

a. Edit each nova configuration file of VMware cluster and resource pool, for
example the /etc/nova/nova-192.0.2.56-443_Cluster1.conf and
/etc/nova/nova-192.0.2.56-443_ResourcePool1.conf files.
b. Add
datastore_cluster_name = DatastoreCluster1

under datastore_regex and remove the datastore_regex attribute.

Note: You can configure only one cluster for datastore_cluster_name.
Regular expression for this option is not supported.
3. Configure the resource pool by editing the nova configuration file of the
resource pool. Note that if the nova compute service is connecting to a real
cluster as in this procedure, you do not need to update the nova configuration
file of the cluster.
The resource pool can be under an ESXi host or under a real cluster. If the
resource pool is under a real cluster, perform the following steps:
a. Change the following attribute:
cluster_name = <resource pool name>

to
cluster_name = <the cluster name under which this resource pool is>

b. Under the cluster_name attribute, add the following attribute:

resource_pool = <the cluster name under which this resource pool is>:<resource pool name>

If the resource pool is under an ESXi host, perform the following steps:
a. Under the cluster_name attribute, add the following attribute:
resource_pool = <the ESXi host name under which this resource pool is>:<resource pool name>

b. Delete the cluster_name option.

For example, if the resource pool is under a real cluster, you must specify the
following attributes in the /etc/nova/nova-192.0.2.56-443_ResourcePool1.conf
file:
cluster_name = Cluster1
resource_pool = Cluster1:ResourcePool1

4. Restart the nova services related to the cluster or resource pool by running the
following commands, for example:
/etc/init.d/openstac-nova-compute-Cluster1 restart
/etc/init.d/openstac-nova-network-Cluster1 restart
/etc/init.d/openstac-nova-compute-ResourcePool1 restart
/etc/init.d/openstac-nova-network-ResourcePool1 restart
Chapter 2. Installing

169

Check the related service status until the status is :-) by running the following
command:
nova availability-zone-list
+-------------------------------------+----------------------------------------+
| Name
| Status
|
+-------------------------------------+----------------------------------------+
| ResourcePool1@vcell10-443
| available
|
| |- ResourcePool1@vcell10-443
|
|
| | |- nova-compute
| enabled :-) 2014-08-29T10:36:25.947820 |
| internal
| available
|
| |- ResourcePool1@vcell10-443
|
|
| | |- nova-network
| enabled :-) 2014-08-29T10:36:21.598537 |
| |- Cluster1@vcell10-443
|
|
| | |- nova-network
| enabled :-) 2014-08-29T10:36:25.207140 |
| |- test-srv05
|
|
| | |- nova-cert
| enabled :-) 2014-08-29T10:36:30.183126 |
| | |- nova-conductor
| enabled :-) 2014-08-29T10:36:23.328309 |
| | |- nova-consoleauth
| enabled :-) 2014-08-29T10:36:22.339324 |
| | |- nova-network
| enabled XXX 2014-08-29T02:39:00.199581 |
| | |- nova-scheduler
| enabled :-) 2014-08-29T10:36:27.273330 |
| | |- nova-smartcloud
| enabled XXX 2014-08-28T02:21:03.956346 |
| Cluster1@vcell10-443
| available
|
| |- Cluster1@vcell10-443
|
|
| | |- nova-compute
| enabled :-) 2014-08-29T10:36:29.350317 |
| nova
| available
|
| |- test-srv05
|
|
| | |- nova-compute
| enabled XXX 2014-08-29T02:38:53.724831 |
+-------------------------------------+----------------------------------------+

You can see the new hypervisor by using the nova hypervisor-list command.
In the output the hypervisor_name is the same as the resource pool specified in
the nova configuration file. For example:
| 178 | Cluster1:ResourcePool1 |

5. To ensure that the hypervisor ID is not changed after the manual configuration,
you must run the change_compute_id.sh script on the VMware region node.
For example, if your original hypervisor ID is 102:
| 102 | resgroup-87(ResourcePool1) |

after the manual configuration, 102 was marked as deleted in database. You can
only see the new hypervisor 178 by using the nova hypervisor-list command:
| 178 | Cluster1:ResourcePool1 |

Note: The original hypervisor 102 is not shown by using the nova
hypervisor-list command' after the manual configuration. You must record
this ID before starting this procedure.
Log on to your VMware region node, and run following command:
cd /opt/ibm/orchestrator/hypervisor_tool
./change_compute_id.sh --org_id 178 --new_id 102

Note: If resgroup- is a prefix of the hypervisor name, it must be a resource

pool in vCenter. You must follow this post configuration step to configure it,
otherwise you can not boot the virtual machine successfully.
6. Restart the nova services related to the resource pool and the nova scheduler
service by running the following commands:
/etc/init.d/openstac-nova-compute-ResourcePool1 restart
/etc/init.d/openstac-nova-network-ResourcePool1 restart
/etc/init.d/openstack-nova-scheduler restart

170

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Check the related services status until the status is :-).

7. Try to run OpenStack CLI to boot the virtual machine to ensure that OpenStack
works.
Log on the VMware region and try the following commands to boot virtual
machines:
source /root/openrc
nova boot --flavor 1 --image <your image id> --availability-zone \
ResourcePool1@vcell10-443 testenv1

Check that the virtual machines status to ensure it is active.

Upgrading from IBM Cloud Orchestrator V2.4 on distributed

deployment
You can upgrade from IBM Cloud Orchestrator V2.4 to IBM Cloud Orchestrator
V2.4.0.1 or V2.4.0.2, or upgrade from IBM Cloud Orchestrator V2.4.0.1 to IBM
Cloud Orchestrator V2.4.0.2.

Before you begin

Before you upgrade, complete the following steps:
1. Back up the Deployment Server, the Central Servers, the Region Servers, and
the Compute Nodes.
[VMware only:] For information about how to take snapshots of
VMware-hosted Central Servers and Region Servers, see http://
pubs.vmware.com/vsphere-50/index.jsp?topic=
%2Fcom.vmware.vsphere.vm_admin.doc_50%2FGUID-64B866EF-7636-401CA8FF-2B4584D9CA72.html.
2. Temporarily ensure that your IBM Cloud Orchestrator passwords do not
include any special characters, or the upgrade is likely to fail.
During installation and upgrade, IBM Cloud Orchestrator passwords can
contain only alphanumeric characters and underscores (0-9 a-z A-Z _). Spaces,
hyphens, and other special characters are not allowed. If necessary, change the
passwords to remove any special characters until after the upgrade is complete.
For instructions about how to change the passwords, see Changing the various
passwords on page 127.
It is not necessary to remove the special characters from operating system (OS)
passwords.
3. Download the image files required for the upgrade, as described in
Downloading the required image files on page 32.
[Optional] You do not have to be a root user to upgrade IBM Cloud Orchestrator.
A nonroot user can upgrade if the user has sudo access privileges. To configure a
user with sudo access privileges, add the following line to the /etc/sudoers file:
<user> ALL=(ALL)NOPASSWD:ALL

About this task

You must have already unpacked the IBM Cloud Orchestrator installation package
into a temporary directory on the Deployment Server. In this procedure, the
example temporary directory is /opt/ico_install_2402. Replace
/opt/ico_install_2402 with the appropriate value for your installation.
To upgrade IBM Cloud Orchestrator, complete the following procedure.
Chapter 2. Installing

171

Upgrading the Deployment Server

1. Edit the /opt/ico_install_2402/installer/deployment-service.cfg
configuration file, as described in Installing the Deployment Service on page
34.
[Optional:] Copy the values from the original configuration file (for example,
/opt/ico_install/installer/deployment-service.cfg) to the new
configuration file.
2. Upgrade the Deployment Service by running the following command:
cd /opt/ico_install_2402/installer; sudo ./deploy_deployment_service.sh

3. If the upgrade does not complete successfully, review the following log files:
v /var/log/cloud-deployer/deployer_bootstrap.log
v /var/log/cloud-deployer/deploy.log
Take the appropriate action as indicated in the log files, and repeat step 2.
Upgrading the deployed IBM Cloud Orchestrator environment
1. Log on to Central Server 1.
2. Stop all services by running the following command:
/opt/ibm/orchestrator/scorchestrator/SCOrchestrator.py stop

3. Log on to the Deployment Server.

4. [VMware only] Remove VMware database migration resources from the
upgrade template for a VMware region by running the following command:
/usr/bin/ico-upgrade-tool prepare-upgrade

5. Identify the job ID of the Central Servers deployment job:

a. Use the ds job-list command to display the job details.
Example:
source ~/openrc
ds job-list

Example output:
+--------------------------------------+---------------+---------| id
| name
| status
+--------------------------------------+---------------+---------| 8e362f0d-ed86-4bfc-8d69-46c22fb276d9 | central-61719 | FINISHED
| 5cc5ecbe-64a7-4ecd-a025-3c701bbeaa22 | vmware-61719 | FINISHED
| fdf06d31-3cea-4d97-8dfd-8ce566a2d5c4 | kvm-61719
| FINISHED
+--------------------------------------+---------------+---------+--------------------------------------+---------------------------------| pjob_id
| created_at
+--------------------------------------+---------------------------------|
| 2014-10-16 09:57:48.558388-04:00
| 8e362f0d-ed86-4bfc-8d69-46c22fb276d9 | 2014-10-16 13:51:17.893313-04:00
| 8e362f0d-ed86-4bfc-8d69-46c22fb276d9 | 2014-10-16 14:01:56.507769-04:00
+--------------------------------------+---------------------------------+----------------------------------+
| updated_at
|
+----------------------------------+
| 2014-10-16 13:50:36.952918-04:00 |
| 2014-10-16 14:23:21.450570-04:00 |
| 2014-10-16 14:36:00.528696-04:00 |
+----------------------------------+

b. Make a note of the job ID.

In this example, the job ID is 8e362f0d-ed86-4bfc-8d69-46c22fb276d9.
6. Upgrade the IBM Cloud Orchestrator Central Servers by running the
following command:
ds job-update 8e362f0d-ed86-4bfc-8d69-46c22fb276d9 \
-P "OrchestratorPassword=myICOadminPassword;DataBasePassword=myDB2inst1Password;BPMDBPassword=myBPMadminPassword"

172

IBM Cloud Orchestrator 2.4.0.2: User's Guide

where
myICOadminPassword
The password for the default Cloud Administrator user (admin). The
admin user is used for internal connectivity across all of the IBM
Cloud Orchestrator components.
myDB2inst1Password
The password for the IBM DB2 database user (db2inst1).
myBPMadminPassword
The password for the admin user for Business Process Manager
(bpm_admin).
Note: In accordance with security best practices, it is assumed that the default
passwords were changed after the original installation. Therefore, to update
the deployment environment and to avoid resetting the passwords to the
original installation values, you must specify the current passwords in the ds
job-update command. During installation or upgrade, you must specify
passwords that do not contain any special characters.
Important: Do not run any other ds job-update command until the Central
Servers job is finished.
7. Check the status of the upgrade job by running the ds job-list command.
When the status of the Central Servers upgrade job is UPDATE_FINISHED,
proceed to the next step. If the upgrade job does not complete successfully,
review the log files in the /var/log/ds directory and take the appropriate
action.
8. Identify the job ID for each Region Server deployment by running the ds
job-list command.
In this example, the Region Server job IDs are 5cc5ecbe-64a7-4ecd-a0253c701bbeaa22 and fdf06d31-3cea-4d97-8dfd-8ce566a2d5c4.
9. Upgrade the Region Servers by running the following command for each
Region Server:
ds job-update Region_Server_Job_ID

Example:
ds job-update 5cc5ecbe-64a7-4ecd-a025-3c701bbeaa22
ds job-update fdf06d31-3cea-4d97-8dfd-8ce566a2d5c4

You can upgrade several Region Servers in parallel.

10. Check the status of the upgrade jobs by running the ds job-list command.
If any upgrade job does not complete successfully, review the information in
Troubleshooting upgrade on page 196 and take the appropriate action.
When the status of each Region Server upgrade job is UPDATE_FINISHED,
proceed to the next step.
11. Reapply any OpenStack customizations that are not part of the default
configuration.
The following OpenStack configuration files are backed up by the upgrade
process:
Server

Component

Configuration files

Central
Server
1

Ceilometer

/etc/ceilometer/ceilometer.conf

Chapter 2. Installing

173

Server

Component

Configuration files

Central
Server
2

Keystone

/etc/keystone/keystone.conf
/etc/keystone/keystone-paste.ini
/etc/keystone/policy.json

Region
Server

Nova

/etc/nova/nova.conf

Glance

/etc/glance/glance-registry.conf
/etc/glance/glance-api.conf

Heat

/etc/heat/heat.conf

Cinder

/etc/cinder/cinder.conf

VMware
discovery
(VMware
only)

/etc/vmware-discovery.conf

Neutron Neutron
Server

/etc/neutron/neutron.conf

The original configuration files are copied to the /var/chef/backup/etc

directory on the relevant server.
After the upgrade, compare each original configuration file with the latest
version, as follows:
diff /var/chef/backup/etc/componentName/fileName.chef-timestampOfBackup /etc/componentName/fileName

For example:
diff /var/chef/backup/etc/nova/nova.conf.chef-20141112145321.465905 /etc/nova/nova.conf

If required, reapply any customizations.

12. Restart the Central Server services, as described in Managing IBM Cloud
Orchestrator services manually on page 227.
Verifying the upgrade
1. Check the version number, as follows:
a. Log in to the Self-service user interface.
b. In the upper-right corner, click the About link.
c. Verify that the correct version number is displayed in the About window.
2. To ensure that the system is upgraded correctly, complete the installation
verification steps, as described in Verifying the installation on page 68.

What to do next
Complete the post-upgrade configuration steps, as described in Configuring IBM
Cloud Orchestrator after upgrading from V2.4 on page 176.

Upgrading from IBM Cloud Orchestrator V2.4 for high

availability
To upgrade from IBM Cloud Orchestrator V2.4 on high availability, complete the
following procedure.

Before you begin

Make sure that your environment is configured correctly:

174

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v The System Automation Application Manager post installation is completely

done and the IBM Cloud Orchestrator management stack can be stopped and
started without error.
v System Automation Application Manager is configured as upstart service with
the name saam.
v Before the upgrade, the IBM Cloud Orchestrator management stack is correctly
shown as online.
Prepare for the upgrade by performing the following steps:
1. Stop the IBM Cloud Orchestrator management stack in System Automation
Application Manager by running the following command on the System
Automation Application Manager virtual machine:
eezcs -D SCOsaam -c resreq -o stop "Cloud Orchestrator"

2. Wait until the System Automation Application Manager user interface shows
that the IBM Cloud Orchestrator management stack can be stopped. You can
also verify it by running the following commands on the System Automation
Application Manager virtual machine:
eezcs -D SCOsaam -c lsres -Ab -r "Cloud Orchestrator" |
grep ObservedState | cut -d = -f 2 | tr -d

The command should return Offline.

3. Stop the System Automation Application Manager manually:
stop saam

4. Manually start the external DB2 again by running service db2ctrl start on
the server where the external DB2 runs.
5. Verify that the Deployment Service environment works correctly by running the
following command on the Deployment Service virtual machine:
source /root/keystonerc; ds job-list

6. Verify that all deployments that you want to update are in the FINISHED state.

Procedure
1. Upgrade the Deployment Service and the management stack topologies by
following the procedure described at Upgrading from IBM Cloud Orchestrator
V2.4 on distributed deployment on page 171.
2. Upgrade the IBM Cloud Orchestrator management stack.
Upgrade the System Automation Application Manager deployment. To do this,
select the ID of the deployment job. You can display the deployment jobs by
running the following command:
[root@cil021029129 ~]# ds job-list
+--------------------------------------+---------------+---------| id
| name
| status
+--------------------------------------+---------------+---------| 8e362f0d-ed86-4bfc-8d69-46c22fb276d9 | central-61719 | FINISHED
| baf4892b-daa1-48b5-bf96-820c9f0b0725 | saam-61719
| FINISHED
| 5cc5ecbe-64a7-4ecd-a025-3c701bbeaa22 | vmware-61719 | FINISHED
| fdf06d31-3cea-4d97-8dfd-8ce566a2d5c4 | kvm-61719
| FINISHED
+--------------------------------------+---------------+---------+--------------------------------------+---------------------------------| pjob_id
| created_at
+--------------------------------------+---------------------------------|
| 2014-10-16 09:57:48.558388-04:00
|
| 2014-10-16 09:56:54.539352-04:00
| 8e362f0d-ed86-4bfc-8d69-46c22fb276d9 | 2014-10-16 13:51:17.893313-04:00
Chapter 2. Installing

175

| 8e362f0d-ed86-4bfc-8d69-46c22fb276d9 | 2014-10-16 14:01:56.507769-04:00

+--------------------------------------+---------------------------------+----------------------------------+
| updated_at
|
+----------------------------------+
| 2014-10-16 13:50:36.952918-04:00 |
| 2014-10-16 10:58:44.591381-04:00 |
| 2014-10-16 14:23:21.450570-04:00 |
| 2014-10-16 14:36:00.528696-04:00 |
+----------------------------------+

The ID in this example is baf4892b-daa1-48b5-bf96-820c9f0b0725. Therefore,

the command to start the update is: ds job-update baf4892b-daa1-48b5-bf96820c9f0b0725.
After the job update is done, the state changes to UPDATE-FINISHED. Then
update the deployment for the Central Server by executing the command above
with the ID of the deployment job for the Central Servers. Wait until the
Central Servers update has finished successfully. Finally, upgrade all Region
Server deployments.
If the upgrade does not complete successfully, review the information in
Troubleshooting upgrade on page 196.
3. Execute the post upgrade actions.

What to do next
Post upgrade activities:
1. Configure the external database as described in Configuring the external
database server for the high-availability topology on page 119.
2. Configure System Automation Application Manager again as described in
Configuring System Automation Application Manager on page 122.
3. Verify that you can manage the IBM Cloud Orchestrator management stack
correctly.
4. To start the IBM Cloud Orchestrator management stack again, cancel the stop
request you issued before the upgrade by running the following command:
eezcs -D SCOsaam -c resreq -o cancel "Cloud Orchestrator"

5. Complete the post-upgrade configuration steps, as described in Configuring

IBM Cloud Orchestrator after upgrading from V2.4.

Configuring IBM Cloud Orchestrator after upgrading from V2.4

During the upgrade process from V2.4.0.0 to V2.4.0.1 or V2.4.0.2, the existing
Categories, Actions, and Offerings are not updated. To update these artifacts to
apply the changes made in V2.4.0.1 or V2.4.0.2, perform the following tasks.

Updating the Edit Instance Type Tags action

1. Log in to the Self-service user interface as a Cloud Administrator.
2. Click CONFIGURATION > Actions Registry.
3. Scroll through the list of actions in the Actions Registry, and select the Edit
Instance Type Tags action.
4. From the Actions menu on the left, click Edit Action.
5. Change the name to Edit Resource Type Tags, and optionally provide a
description.
6. Change the item selection criteria to createInstanceAction.

176

IBM Cloud Orchestrator 2.4.0.2: User's Guide

7. Click OK.
8. From the Actions menu on the left, click Edit Resource Type Tags.
9. For each of the following resource types, remove the specified tags by clicking
the delete icon and then clicking OK:
Table 15.
Resource type

Tags to remove

Offering

enabled, disabled, hidden

Action

enabled, disabled, hidden

Category

all

Creating an action to resize virtual machines

To use the Business Process Manager process to resize virtual machines, create a
resize action in the Actions Registry:
1. Log in to the Self-service user interface as a Cloud Administrator.
2. Click CONFIGURATION > Actions Registry.
3. From the Actions menu on the left, click Create Action.
4. Enter a name for the resize action (for example, Resize), select an icon, and
optionally provide a description.
5. Select openstackvms as the resource type.
6. Select the heat, nova, vsys, and vsysnext tags.
7. Select singleInstanceAction as the item selection criteria.
8. Select SCOrchestrator Nova Support Toolkit - SCONOVA as the filter.
9. Select Resize Virtual Machine - SCOrchestrator Nova Support Toolkit as
the process. The Human Service field is left blank.
10. Click Create.

Renaming categories
In the Self Service Catalog in V2.4.0.2, some categories were renamed. If you want
to rename these categories in your upgraded system, complete the following steps:
1. Log in to the Self-service user interface as a Cloud Administrator.
2. Click CONFIGURATION > Self-Service Catalog.
3. Click the Categories tab.
4. Select the Create resources for cloud services category.
5. From the Actions menu on the left, click Edit Category.
6. Edit the category as follows:
a. Change the name to Manage the lifecycle of cloud services.
b. Change the description to A set of offerings to manage the lifecycle
of cloud services such as virtual servers, patterns and stacks.
c. From the Icon list, select Configuration Category Icon.
d. Click OK.
7. Select the Infrastructure management category.
8. From the Actions menu on the left, click Edit Category.
9. Change the name to Infrastructure management services and click OK.
10. Select the Deploy cloud services category.
Chapter 2. Installing

177

11. From the Actions menu on the left, click Edit Category.
12. Change the description to A set of offerings to deploy cloud services
such as virtual machines and resource patterns and click OK.

Moving offerings to different categories

In the Service Catalog in V2.4.0.1 and V2.4.0.2, the following offerings were moved
to different categories:
Table 16.
Category in V2.4.0.1 or
V2.4.0.2

Offering

Category in V2.4.0

Register a key to enable

access to virtual servers

Infrastructure management
services

Deploy cloud services

Unregister keys

Infrastructure management
services

Deploy cloud services

Decommission a cloud
service

Deploy cloud services

Manage the lifecycle of cloud

services

If you want to move the offerings, perform the following steps for each of the
specified offerings:
1.
2.
3.
4.
5.

Log in to the Self-service user interface as a Cloud Administrator.

Click CONFIGURATION > Self-Service Catalog.
Click the Offerings tab.
Select the offering that you want to move to a different category.
From the Actions menu on the left, click Edit Offering.

6. Change the category to the target category as specified in the previous table
and click OK.

Modifying access control lists

In V2.4.0.1 and V2.4.0.2, the following offerings in the Virtual System Operations
(Single Instances) and Virtual System Operations (Multiple Instances) categories are
visible only to the Cloud Administrator. However, in a system that has been
upgraded, these categories are available to any role.
v Start Virtual System Instance
v Stop Virtual System Instance
v Restart Virtual System Instance
v
v
v
v
v

Delete Virtual System Instance

Change End Time Of Virtual System Instance
Change Limits Of Environment Profile
Start Virtual System Instance by selecting a single virtual machine
Stop Virtual System Instance by selecting a single virtual machine

v Restart Virtual System Instance by selecting a single virtual machine

v Delete Virtual System Instance by selecting a single virtual machine
v
v
v
v

178

Modify Single Server Virtual System Instance

Start Multiple Virtual System Instances
Stop Multiple Virtual System Instances
Restart Multiple Virtual System Instances

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Delete Multiple Virtual System Instances

To modify the access control list to restrict access to these offerings, complete the
following steps:
1. Log in to the Self-service user interface as a Cloud Administrator.
2. Click CONFIGURATION > Self-Service Catalog.
3. Click the Offerings tab.
4. For each specified offering, complete the following steps:
a. Select the offering.
b. From the Actions menu on the left, click Modify Access Control List.
c. Remove the existing ACL entry for the Any role.
d. From the Domain list, select Any.
e. From the Project list, select Any.
f. From the Role list, select domain_admin.
g. Select all of the check boxes and click Add to Access Control List.
h. Click OK.

Renaming processes as actions

For the Edit Offering and Edit Category actions, the associated Business Process
Manager process must be changed as shown in the following table:
Table 17.
Action

New process

Edit Offering

Edit Offering Action

Edit Category

Edit Category Action

1. Log in to the Self-service user interface as a Cloud Administrator.

2. Click CONFIGURATION > Actions Registry.
3. For each of the actions listed in the above table, complete the following steps:
a. Scroll through the list of actions in the Actions Registry, and select the
specified action.
b. From the Actions menu on the left, click Edit Action.
c. Update the process as specified in the previous table.
d. Click OK to save the action.

Ensuring that cloud groups are connected

Ensure that the hypervisors are started and that the cloud groups are connected, as
follows:
1. Log in to the Self-service user interface as a Cloud Administrator.
2. Click PATTERNS > Deployer Configuration > Cloud Groups.
3. If a cloud group is displaying a yellow icon with an exclamation mark, select
the cloud group to see its details:
v If the Current status field shows You must start at least one hypervisor to
create virtual systems, expand the Cloud hardware section and click on the
hypervisor to display details page.
v If the field Current status shows a message similar to the following one:

Chapter 2. Installing

179

An internal error occurred while accessing hypervisor:

Unable to obtain a valid service API version for endpoint:
http://192.0.2.0:8774/v2/46cd3efb9a9245e9aa971516e308a92b

and before the upgrade the hypervisor was working correctly, click Maintain
and then click Start to enable the hypervisor.
After this step, the hypervisor status should be Started and the cloud group
status should be Connected.

Updating the customizations.json files

Update the customizations.json file on each server to ensure that the format of
the upgraded V2.4.0.1 or V2.4.0.2 JSON files are the same as the freshly installed
files. For example, on Central Server 2, check the content of the
/opt/ibm/ccs/scui/etc/customizations/default/customizations.json file.
The file should have the same content as described in the "Style properties" section
in Metadata file properties in customization file on page 246.

Upgrading the Public Cloud Gateway

If you are connecting to public clouds by using the Public Cloud Gateway,
complete the upgrade activities related to the Public Cloud Gateway as described
in Upgrading on page 673.

Strengthening the IBM Cloud Orchestrator passwords

In accordance with security best practices, when you have verified that the
upgrade completed successfully, consider changing the IBM Cloud Orchestrator
passwords to include special characters, as described in Changing the various
passwords on page 127.

What to do next
Disable the SSLv3 protocol as described in Disabling SSLv3 protocol in deployed
instances.

Disabling SSLv3 protocol in deployed instances

After upgrading to IBM Cloud Orchestrator V2.4.0.2, you must disable the SSLv3
protocol, due to a vulnerability that has been referred to as the Padding Oracle On
Downgraded Legacy Encryption (POODLE) attack.

Before you begin

Upgrade to IBM Cloud Orchestrator V2.4.0.2, and upgrade to caching service
V2.1.0.4.
Note: Caching service V2.1.0.0 and earlier instances cannot be upgraded to caching
service V2.1.0.4. For these instances, you must delete any existing caching service
prior to upgrading the foundation pattern types. After the foundation pattern types
upgrade, deploy the new caching service instances of service V2.1.0.4 as described
in the following procedure.

180

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

This task describes mitigation procedures for deployed instances of virtual
applications, shared services, and virtual systems, in addition to deployed
instances of classic virtual systems. After you upgrade and apply the mitigation
steps and the JRE upgrade emergency fix, Java management processes that are
running on deployed virtual machines are configured to support the SSL_TLSv2
protocol suite. The SSL_TLSv2 protocol suite enables TLSv1.2, TLSv1.1, TLSv1, and
SSLv3 in this precedence order. SSLv3 is disabled by JRE default, therefore,
SSL_TLSv2 only enables the TLS protocols: TLSv1.2, TLSv1.1, and TLSv1. At
runtime during client and server SSL handshake, the best protocol that the client
and server have in common is selected. For example, TLSv1.2 is selected if both
support TLSv1.2. For more information on JRE default protocol configuration, see
Alternative mitigation options.
Using IBM OS Images for Red Hat Linux Systems
Download IBM OS Image for Red Hat Linux Systems: 2.1.1.0 (RHEL 6.6 image)
from the IBM Passport Advantage Online website. This image contains the
required JRE upgrade of JDK6: SR16 FP3 or later.
Note: SSLv3 is disabled by JRE default policy in the new base operating system
images unless you remove the jdk.tls.disabledAlgorithms=SSLv3 property from
the JRE java.security file.
Using custom images
Custom images include the following types of image:
Cloud-init (cloudbase-init) activated images
For instances running on cloud-init (cloudbase-init) activated images, to
disable SSLv3 you must complete the steps listed in Updating existing
virtual application, shared services, and virtual system deployed instances.
You do not need to rebuild the image because JRE is not required for the
cloud-init (cloudbase-init) activated images in order to use them for virtual
system instances.
IBM SmartCloud Orchestrator V2.3 or V2.3.0.1 images
For instances running on IBM SmartCloud Orchestrator V2.3 or V2.3.0.1
images, to disable SSLv3 you must complete the steps listed in Updating
existing virtual system classic instances. To remove the vulnerability for
new instances created with IBM SmartCloud Orchestrator V2.3 or V2.3.0.1
images, you must update the JRE that is embedded within such images.
Prerequisites for creating new instances
For new pattern deployments that use new base operating system images,
complete the following steps:
v For new virtual application, shared service, and virtual system deployments, use
the following procedure to change the default deployment settings in order to
add the new operating system images:
1. Click Cloud > Default Deploy Settings.
2. In the Action menu, click Delete to delete the old base operating system
image.
3. Click Add to add the new version of the base operating system image.

Chapter 2. Installing

181

v For new classic virtual system deployments, use the new patterns that are built
on the new operating system images.
Updating existing virtual application, shared services, and virtual system
deployed instances
To disable SSLv3 protocol in virtual application, shared services, and virtual
system deployed instances, complete the following steps.
Important: You must do these steps in the specified order or the fix will not be
successful.
1. Upgrade the pattern type to the following version:
Foundation-ptype Version 2.1.0.3

Ensure that the pattern type is imported and enabled.

2. For each virtual application and virtual system instance that is running on Intel
operating systems (ESX hypervisor backend), use the following steps to disable
the automatic snapshot before applying the emergency fix:
a. Click Patterns > Pattern Instances and select the instance type.

3.
4.
5.
6.
7.

b. Click the instance. The instance details are displayed.

c. Scroll to From pattern and expand Snapshots.
d. Click Disable Automatic Snapshots.
For each virtual application and virtual system instance, open the details page
for the instance and click Check for updates.
Upload the IBM Cloud Orchestrator 2.4.0.2 JRE emergency fix to the catalog.
Apply the IBM Cloud Orchestrator 2.4.0.2 JRE emergency fix to each virtual
application, shared service, and virtual system instance.
Restart each instance or individual virtual machine so that the JRE updates take
effect.
Verify that SSLv3 is disabled and that the deployed virtual machine supports
TLSv1.2 protocols, by running the following command:
deployer.virtualapplications.get("deployment_id").virtualmachines[number].check_compliance()

Example:
deployer.virtualapplications.get("d-4e04e98d-8c3d-4bec-bab1-ca033419ffc3").virtualmachines[0].check_compliance()

8. Deploy a new caching service instance by using the new version of the caching
service plug-in, as follows:
a. Click Manage > Operations > CachingMaster, Grid Administration >
Create grid to go to the new caching service instance.
b. Create a session grid with a dedicated user name and password and a
proper grid cap for the web application.
c. Use a Secure Shell (SSH) connection to connect to the virtual machine where
WebSphere Application Server is running.
d. Run the following command on one line:
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/wsadmin.sh
-lang jython

e. Run the following command on one line to configure the web application's
session management with the new caching service IP, user, password, and
grid name. The following command uses the example of configuring the
HttpSessionSample.war web application.

182

IBM Cloud Orchestrator 2.4.0.2: User's Guide

AdminApp.edit('HttpSessionSample.war', '[-SessionManagement
[[true XC10SessionManagement "' + caching_service_instance_ip
+ ':!:' + user_name + ':!:' + password + ':!:' + grid_name ]]])

f. Locate the web application's splicer.properties file, and set

reuseSessionId=true.
g. Restart WebSphere Application Server so that the new configuration takes
effect.
Updating existing virtual system classic instances
To disable SSLv3 protocol in classic virtual system deployed instances, use a Secure
Shell (SSH) connection to connect to each virtual machine and complete the
following steps.
Important: You must do these steps in the specified order or the fix will not be
successful.
1. Use one of the following procedures to upgrade pattern types:
v Directly apply the emergency fix:
a. Upload the poodle_vsys_ifix.zip file to the IBM Cloud Orchestrator
catalog.
b. Apply the emergency fix to the classic virtual system instance.
v For classic virtual system instances where the root account login is disabled,
the following steps apply only if the /0config directory exists (or c:\0config
on Microsoft Windows):
a. Copy the update.py file and the monitoring_parms.json file to each
virtual machine.
For Linux and AIX virtual machines, copy the two files to the /0config
directory. For Windows virtual machines, copy the two files to the
C:\0config directory.
b. Run the following command from the /0config directory:
python update.py

For Windows, open a command-line window with Administrator

privileges (Run as Administrator) and run the command.
The python script does the following actions:
1) Updates the topology using the latest plugins from foundation-ptype
Version 2.1 if it exists on the virtual machine.
2) Stops the Workload Deployer management and monitoring processes
on the virtual machine.
3) Cleans up related paths and files.
4) Relaunches the 0config initialization process to upgrade
foundation-ptype, if necessary.
2. Upload the IBM Cloud Orchestrator 2.4.0.2 JRE emergency fix to the catalog.
3. Apply the IBM Cloud Orchestrator 2.4.0.2 JRE emergency fix to the extended
classic virtual system instance.
Note: While applying the fix to each instance running on Intel operating
systems, clear the Take a snapshot before service is applied check box.
4. Restart your virtual machine so that the updates take effect.
5. Verify that SSLv3 is disabled and that the deployed virtual machine supports
TLSv1.2 protocols:
Chapter 2. Installing

183

a. Run the following command:

openssl s_client -connect vm_ip:9999

where vm_ip is the IP address of the deployed virtual machine.

b. SSH into each virtual machine and run the following command:
/opt/IBM/ibm_java_dir/jre/bin/java -version

For virtual machines running JRE6 (classic virtual system instances), the
version is updated to SR16 FP3. For virtual machines running JRE7 (shared
service, virtual applications, and virtual system instances), the version is
updated to SR8 FP10.
c. Run the following command:
openssl s_client -connect vm_ip:9999 -ssl3

where vm_ip is the IP address of the deployed virtual machine.

Disabling SSLv3 protocol in Workload Deployer component
After all instances are upgraded as described in this topic, you must turn off the
SSLv3 support on the Workload Deployer component. SSLv3 can be disabled by
JRE default policy. You must add the jdk.tls.disabledAlgorithms=SSLv3 property
to the JRE java.security file located on the Workload Deployer node at the
following location:
/opt/ibm/javax86_64-70/jre/lib/security/java.security

Uninstalling
To remove a KVM compute node, or to remove a region, complete these steps.

Removing a KVM compute node

To remove a KVM compute node from IBM Cloud Orchestrator, perform the
following steps.

Procedure
1. List the services on all the compute nodes:
On the Region Server, run:. ~/openrc && nova service-list
+------------------+--------------+----------+---------+-------+----------------------------+
| Binary
| Host
| Zone
| Status | State | Updated_at
|
+------------------+--------------+----------+---------+-------+----------------------------+
| nova-cells
| rs-135-3
| internal | enabled | up
| 2013-10-09T06:47:41.699503 |
| nova-cert
| rs-135-3
| internal | enabled | up
| 2013-10-09T06:47:48.464156 |
| nova-compute
| rs-5-blade-6 | nova
| enabled | up
| 2013-10-09T06:47:42.402192 |
| nova-conductor | rs-135-3
| internal | enabled | up
| 2013-10-09T06:47:49.713611 |
| nova-network
| rs-5-blade-6 | internal | enabled | up
| 2013-10-09T02:47:32.317892 |
| nova-consoleauth | rs-135-3
| internal | enabled | up
| 2013-10-09T06:47:49.928091 |
| nova-scheduler | rs-135-3
| internal | enabled | up
| 2013-10-09T06:47:49.929776 |
+------------------+--------------+----------+---------+-------+----------------------------+

2. Disable the nova compute and nova network service on the compute node you
want to remove. On the Region Server, run: nova-manage service disable
--host=<host> --service=<services>.
For example, if you want to remove node rs-5-blade-6, run the following
commands:
nova-manage service disable --host=rs-5-blade-6 --service=nova-network
nova-manage service disable --host=rs-5-blade-6 --service=nova-compute

184

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. If you want to remove the compute node completely, you must manually
remove it from the database, create a file drop_node.sql with following
contents:
connect to openstac user <dbuser> using <dbpassword>
delete from compute_node_stats where compute_node_id in
(select id from compute_nodes
where hypervisor_hostname=rs-5-blade-6)
delete from compute_nodes where hypervisor_hostname=rs-5-blade-6
delete from services where host=rs-5-blade-6

Log on to central server(share db) / region server(non-shared db) with

user db2inst1 and run the sql script:
su - db2inst1
db2 -tf drop_node.sql

Note: The compute_node_stats table exists only in environments that were

upgraded from IBM SmartCloud Orchestrator V2.3 or V2.3.0.1.
4. (Optional, this step is required before re-adding a removed compute back to the
region server). On the compute node, clean the OpenStack packages. Find the
packages needed to remove: rpm -qa | grep "*openstack*". Remove the
packages using the command: rpm -e <package name>
5. (Optional, this step is required before re-adding a removed compute back to the
region server). Restore the network configuration of the compute node. Remove
the bridge which created by the IBM Cloud Orchestrator installer and reassign
the IP back to ethX interface.
6. Delete the node from the Deployment Server by using the ds node-delete
command.

What to do next
The availability zone will be removed from the OpenStack region after all the
compute nodes that used this availability zone are removed. You can run the
command nova availability-zone-list to find the compute nodes that use the
availability zone.

Removing a region
To remove a region from the IBM Cloud Orchestrator environment, perform the
following steps.

Procedure
1. The IBM Cloud Orchestrator administrator must delete all the instances on the
region:
v Log on to the Self-service user interface and click ASSIGNED RESOURCES.
v Select All Regions or the region that you want to delete. The virtual
machines listed are only the ones related to the region. Delete all of them.
2. On Central Server 2, update the Keystone entries that relate to the region that
you want to remove, for example, RegionOne:
source /root/keystonerc
keystone endpoint-list |grep RegionOne | cut -d | -f2 | while read endpoint;
do keystone endpoint-delete $endpoint;
done

3. Update the IBM Cloud Orchestrator environment as follows:

v Delete the region cloud groups:
a. Click PATTERNS > Deployer Configuration > Cloud Groups.
Chapter 2. Installing

185

b. Select the cloud group for the region you are deleting and click Discover.
c. Select each cloud group related to the region and click Delete.
v Delete the region IP group:
a. Click PATTERNS > Deployer Configuration > IP Groups.
b. Select the required IP group and click Delete.
4.

Remove the region environment from the IBM Cloud Orchestrator tool:
a. Go to the /opt/ibm/orchestrator/scorchestrator directory on Central
Server 1.
b. Remove the SCOEnvironment_<removed_region>.xml file.
c. Run the SCOEnvironment_update.py script.
d. Check that all the node information of the removed region is not present
anymore in the SCOEnvironment_fulltopo.xml file.
e. Run the SCOrchestrator.py --status command to check if the status of the
removed region is gone.

Troubleshooting installation
Learn how to troubleshoot installation problems.
To troubleshoot problems that occurred during the installation procedure, you can
perform the following actions:
v Check the log files.
For the Deployment Service, the log files are located in the /var/log/clouddeployer directory.
To do the problem determination for the ds command, refer to the log files
located in the /var/log/ds directory.
ds-api.log
This log is for ds-api service.
ds-engine.log
This log is for ds-engine service.
ds-engine-<job_id>.log
This log is generated when running the ds job-execute command. The
knife command outputs are recorded in this log file for each job.
If any problem occurs when running the chef bootstrap command, check the
/var/chef/cache/chef-stacktrace.out log file in the target system.
v Check error details for job execution
Use the ds job-show <JOB_ID> command to show the error details in the fault
section. For example:
ds job-show aa00eb97-5d83-4acb-9589-dc8b654a6d91
+------------+-------------------------------------------------------------------------------------+
| Property
| Value
|
+------------+-------------------------------------------------------------------------------------+
| created_at | 2014-03-27T05:47:38.271874
|
| deleted_at | None
|
| fault
| {
|
|
|
"message": "Failed to execute task from compose-topo-roles : create chef roles
|
|
|
for deployment",
|
|
|
"exception": [
|
|
|
"Traceback (most recent call last):\n",
|
|
|
" File \"/usr/lib/python2.6/site-packages/ds/engine/deploy/task_runner.py\",
|
|
|
line 70, in execute\n
res = task.execute(self.context, logger)\n",
|
|
|
" File \"/usr/lib/python2.6/site-packages/ds/engine/deploy/common/
|
|
|
compose_topo_roles.py\", line 77, in execute\n
res_name, resource)\n",
|

186

IBM Cloud Orchestrator 2.4.0.2: User's Guide

|
|
" File \"/usr/lib/python2.6/site-packages/ds/engine/deploy/resource_handler/
|
|
|
node_handler.py\", line 14,in parse\n usr = res[\"Properties\"][\"User\"]\n",|
|
|
"KeyError: User\n"
|
|
| ]
|
|
| }
|
| heat_meta | {
|
|
|
"params": null,
|
|
|
"template": {
|
|
|
"AWSTemplateFormatVersion": "2010-09-09",
|
|
|
"Outputs": {
|
|
|
"ORCHESTRATION_DB_ADDR": {
|
|
|
"Value": {
|
|
|
"Fn::GetAtt": [
|
|
|
"control",
|
|
|
"PublicIp"
|

Known installation errors

v Errors of 32-bit library files libstdc++.so.6 and /lib/libpam.so* were not
found in db2prereqcheck.log
The following errors are not critical and can be ignored. The root cause is those
32-bit library files that cannot be found on the 64-bit operating system platform:
Validating "32 bit version of "libstdc++.so.6" " ...
Found the 64 bit "/usr/lib64/libstdc++.so.6" in the following directory "/usr/lib64".
DBT3514W

The db2prereqcheck utility failed to find the following 32-bit library file:
"libstdc++.so.6".

Validating "/lib/libpam.so*" ...

DBT3514W

The db2prereqcheck utility failed to find the following 32-bit library file:
"/lib/libpam.so*".

Validating "32 bit version of "libstdc++.so.6" " ...

DBT3514W The db2prereqcheck utility failed to find the following 32-bit library file:
"/lib/libpam.so*".
WARNING : Requirement not matched.
Requirement not matched for DB2 database "Server" . Version: "10.5.0.2".
Summary of prerequisites that are not met on the current system:
DBT3514W

The db2prereqcheck utility failed to find the following 32-bit library file:
"/lib/libpam.so*".

v Fail to start Compute Service when using non-administrator account to

connect vCenter in VMware region
If the nova Compute Service cannot be started when using the non-administrator
account to connect vCenter in VMware region and has the following errors in
compute.log file, you must check if the account has the minimum permissions
that is required by the OpenStack integration with vCenter, for the detail
privileges list you can refer to the section VMware vCenter service account in
the OpenStack documentation at http://docs.openstack.org/trunk/configreference/content/vmware.html.
<SOAP-ENV:Envelope xmlns:ns0="urn:vim25" xmlns:ns1="<xref format="html"
href="http://schemas.xmlsoap.org/soap/envelope/"
<ns1:Body>
<ns0:TerminateSession>
<ns0:_this type="SessionManager">SessionManager</ns0:_this>
<ns0:sessionId>52c51b92-776a-3b3a-736d-5a341850e2a9</ns0:sessionId>
</ns0:TerminateSession>
</ns1:Body>
</SOAP-ENV:Envelope>
2014-07-07 16:04:34.049 7390 DEBUG nova.virt.vmwareapi.driver
[req-7563f6b2-d9c7-4165-9898-d8813e271015 None None] Server raised fault:
Permission to perform this operation was denied.
_create_session /usr/lib/python2.6/site-packages/nova/virt
/vmwareapi/driver.py:995
Chapter 2. Installing

187

2014-07-07 16:04:34.050 7390 DEBUG nova.virt.vmwareapi.driver

[req-7563f6b2-d9c7-4165-9898-d8813e271015 None None]
_call_method(session=5274632b-4c09-87ce-f2be-bf2659e02c32) failed.
Module: <module nova.virt.vmwareapi.vim_util from
/usr/lib/python2.6/site-packages/nova/virt/vmwareapi/vim_util.py
Method: get_inner_objects. args: [VIM Object,val){
value = "resgroup-119"_type = "ResourcePool"}, vm, VirtualMachine,
[name, runtime.connectionState]]. kwargs: {}.
Iteration: 11. Exception: Error(s) NotAuthenticated occurred in the call to
RetrievePropertiesEx. _call_method
/usr/lib/python2.6/site-packages/nova/virt/vmwareapi/driver.py:1099

v Cannot find attached volume after volume-attach

The nova volume-attach can be used to attach a volume to an instance.
Sometimes, the volume-attach command runs successfully, but when you ran
the fdisk -l, you cannot find the attached volume. After you restart the virtual
machine, the volume can be found. It is an known issue for VMware hosted
system. Many workaround have been used to discover the attached volume
without reboot the guest operating system, such as login the guest operating
system and run the following command:
echo "- - -" > /sys/class/scsi_host/host#/scan

v Failed to install IBM Cloud Orchestrator because the node time is not sync
with deployment service node.
Deployment service will sync the time with the node that used to deploy IBM
Cloud Orchestrator, if the time is different, it will use ntp to sync the time. But
in some case if the ntp service is stopped in deployment service or the network
is not accessible, the synchronization will fail and the installation will fail as
well. You will see error messages in /var/log/ds-engine-<job-id>.log like
following:
14 Jul 21:18:47 ntpdate[3645]: no server suitable for synchronization found
Starting ntpd:
[60G[[0;32m OK [0;39m]
iptables: Saving firewall rules to /etc/sysconfig/iptables:
[60G[[0;32m OK [0;39m]
ip6tables: Saving firewall rules to /etc/sysconfig/ip6tables:
[60G[[0;32m OK [0;39m]
Starting Chef Client, version 11.6.2
Creating a new client identity for central_server_1-zpvlv3x6m4v6 using the validator key.
================================================================================
[31mChef encountered an error attempting to create the client "central_server_1-zpvlv3x6m4v6"
================================================================================

You can manually run ntpdate to verify if the time service is wrong in
deployment service by performing the following steps:
1. ssh to the failed node.
2. Check the /etc/ntp.conf. Find the last line like "server <deployment
service node ip> burst iburst prefer"
3. Stop the ntpd if it is running:
/etc/init.d/ntpd stop

4. Check if the time sync is able to success:

ntpdate <deployment service node ip>

5. You will see the message like:

30 Jul 04:15:46 ntpdate[19267]: adjust time server 192.0.2.55 offset -0.000122 sec

if you see the message like:

30 Jul 04:18:33 ntpdate[19273]: no server suitable for synchronization found

188

IBM Cloud Orchestrator 2.4.0.2: User's Guide

check if ntpd is started in the deployment service node and the network is
accessible , there is no iptables that is blocking the UDP port 123.
v IBM Cloud Orchestrator deployment requires the domain name used in
cookies as one of the parameters of the deployment.
Cookies that are used to implement user interface security features can be set
only for domain names that are not top-level domain names and adhere to the
public suffix list.
To resolve this problem, provide a domain name matching the requirements to
be used in cookies as one of the parameters of the deployment.
v During deployment service installation, you break the installation manually
or power off the deployment service node.
When you try to reinstall the deployment service, the following error occurs.
Errors in the deploy.log file:
[2014-06-02T22:28:22.632128 #2220] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007ff7d9843db0&gt; 2014-06-02 22:28:11.606 6982 TRACE
keystone ProgrammingError: (ProgrammingError)
ibm_db_dbi::ProgrammingError: Statement Execute Failed: [IBM][CLI Driver][DB2/LINUXX8664] SQL0612N
"DOMAIN_ID" is a duplicate name. SQLSTATE=42711 SQLCODE=-612
\nALTER TABLE "user" ADD COLUMN domain_id VARCHAR(64) ()
...
[2014-06-02T22:28:22.689079 #2220] ERROR -- sc-deploy:
install_task.rb::`log_error::#<Thread:0x007ff7d9843db0&gt; Failed to run command chef-client -N
deployment-service -o role[deployment-service] -E deployment-service -l debug

Resolution:
You must reinstall the operation system of deployment service node or restore
the snapshot back, and reinstall deployment service.
v Deployment service installed failed with user provided repository:
Scenario:
The deployment service installation failed, and found information in
/var/log/ds/deployer.log like following:
[2014-08-11T12:14:59.009900 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8> [
2014-08-11T12:14:59-04:00] DEBUG: Executing yum -d0 -e0 -y install
openstack-nova-compute-2014.1.2-201407291735.
ibm.el6.165
I, [2014-08-11T12:15:04.846423 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8> [
2014-08-11T12:15:04-04:00] DEBUG: ---- Begin output of yum -d0 -e0 -y install
openstack-nova-compute-2014.1.2201407291735.ibm.el6.165 ---I, [2014-08-11T12:15:04.846569 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8> [
2014-08-11T12:15:04-04:00] DEBUG: STDOUT: You could try using --skip-broken to
work around the problem
I, [2014-08-11T12:15:04.846694 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
You could try running: rpm -Va --nofiles --nodigest
I, [2014-08-11T12:15:04.846814 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8> [
2014-08-11T12:15:04-04:00] DEBUG: STDERR: Error: Multilib version problems found.
This often means that the root
I, [2014-08-11T12:15:04.846884 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
cause is something else and multilib version checking is just
I, [2014-08-11T12:15:04.846954 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
pointing out that there is a problem. For example:
I, [2014-08-11T12:15:04.847073 #12830] INFO -- sc-deploy:
Chapter 2. Installing

189

exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
I, [2014-08-11T12:15:04.847155 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8> 1.
You have an upgrade for gnutls which is missing some
I, [2014-08-11T12:15:04.847222 #12830] INFO -- sc-deploy:
exec_cmd.rb:`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
dependency that another package requires. Yum is trying to
I, [2014-08-11T12:15:04.847322 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
solve this by installing an older version of gnutls of the
I, [2014-08-11T12:15:04.847389 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
different architecture. If you exclude the bad architecture
I, [2014-08-11T12:15:04.847486 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
yum will tell you what the root cause is (which package
I, [2014-08-11T12:15:04.847554 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
requires what). You can try redoing the upgrade with
I, [2014-08-11T12:15:04.847624 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
exclude gnutls.otherarch ... this should give you an error
I, [2014-08-11T12:15:04.847741 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
message showing the root cause of the problem.
I, [2014-08-11T12:15:04.847810 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
I, [2014-08-11T12:15:04.847920 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8> 2.
You have multiple architectures of gnutls installed, but
I, [2014-08-11T12:15:04.847991 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
yum can only see an upgrade for one of those arcitectures.
I, [2014-08-11T12:15:04.848070 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8> If
you dont want/need both architectures anymore then you
I, [2014-08-11T12:15:04.848180 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
can remove the one with the missing update and everything
I, [2014-08-11T12:15:04.848250 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
will work.
I, [2014-08-11T12:15:04.848342 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>
I, [2014-08-11T12:15:04.848412 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8&gt; 3.
You have duplicate versions of gnutls installed already.
I, [2014-08-11T12:15:04.848501 #12830] INFO -- sc-deploy:
exec_cmd.rb::`run_cmd_log::#<Thread:0x007f99a9d5cbc8>

v Disabling yum lock in each system.

On each Central Server system:
vi /etc/yum/pluginconf.d/refresh-packagekit.conf

Edit the file and change enabled=1 to enabled=0.

v A problem occurs when IBM Cloud Orchestrator installer accesses the
registered Red Hat Network (RHN) repository.
When an RHN repository is chosen to avoid that it automatically upgrades to
the next level of Red Hat, you must run the following command to register
RHN:
rhnreg_ks --use-eus-channel --force --username=<[email protected]> --password=<password>

190

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Cannot create the external database

When you try to create the external database, the create_dbs.sh command fails
with an error Failed to create database database_name with user user_name.

Reason:
IBM DB2 is stopped.

Solution:
Start IBM DB2.
Example:
# su - db2inst1
$ db2stop
11/20/2014 02:49:33
0
0
SQL1032N No start database manager command was issued.
SQL1032N No start database manager command was issued. SQLSTATE=57019
$ db2start
11/20/2014 02:49:46
0
0
SQL1063N DB2START processing was successful.
SQL1063N DB2START processing was successful.
$ exit
logout
# ./create_dbs.sh central
Creating databases: 5/8
Creating databases: 6/8

All-in-one deployment failed

All-in-one IBM Cloud Orchestrator deployment failed with error Failed to create
network.

Reason:
If you provided customized parameters when deploying the all-in-one topology of
IBM Cloud Orchestrator, the parameters are passed directly to OpenStack. If the
parameters are not valid, the network creation will fail. The following error is
displayed in the /var/log/ds/ds-engine-<your job id>.log file:
[2014-08-28 04:13:46,467] 208.43.88.157 Mixlib::ShellOut::ShellCommandFailed
[2014-08-28 04:13:46,467] 208.43.88.157 -----------------------------------[2014-08-28 04:13:46,468] 208.43.88.157 Expected process to exit with [0], but received 1
[2014-08-28 04:13:46,468] 208.43.88.157 ---- Begin output of nova-manage network create
--label=VM Network --fixed_range_v4=10.32.17.224/29 --num_networks=1 --network_size=16
--bridge=br4096 --dns1= --dns2= --bridge_interface=eth1 --vlan=100 ---[2014-08-28 04:13:46,469] 208.43.88.157 STDOUT:
[2014-08-28 04:13:46,469] 208.43.88.157 STDERR: 2014-08-28 04:13:46.353 23527 CRITICAL nova
[-] UnicodeError: Message objects do not support str() because they may contain non-ascii
characters. Please use unicode() or translate() instead.
[2014-08-28 04:13:46,470] 208.43.88.157 ---- End output of nova-manage network create
--label=VM Network --fixed_range_v4=10.32.17.224/29 --num_networks=1 --network_size=16
--bridge=br4096 --dns1= --dns2= --bridge_interface=eth1 --vlan=100 ---[2014-08-28 04:13:46,471] 208.43.88.157 Ran nova-manage network create --label=VM Network
--fixed_range_v4=10.32.17.224/29 --num_networks=1 --network_size=16 --bridge=br4096 --dns1=
--dns2= --bridge_interface=eth1 --vlan=100 returned 1

Solution:
Run the nova-manage command again on the target node and get the real error
messages:

Chapter 2. Installing

191

nova-manage network create --label=VM Network --fixed_range_v4=10.32.17.224/29 \

--num_networks=1 --network_size=16 --bridge=br4096 \
--dns1= --dns2= --bridge_interface=eth1 --vlan=100

It shows ValueError: "The network range is not big enough to fit 1

networks. Network size is 16."
This is because the network defined 10.32.17.224/29 (the network size is 8) is not
able to split to 1 number with size 16. In this case, you must change the parameter
and redeploy IBM Cloud Orchestrator.

Troubleshooting a high-availability installation

Troubleshoot problems that might occur when running a high-availability
installation of IBM Cloud Orchestrator.

Troubleshooting System Automation for Multiplatforms

controlled services
To provide high availability, the services on Central Server 2 and the Region
Servers are clustered on two virtual machines and are controlled by System
Automation for Multiplatforms. A service might be in an error state. You can check
the state of these clusters in the following ways:
v Use the System Automation Application Manager web user interface:
<SAAM_server_hostname>:16311/ibm/console/

v Log on to the command line of a cluster virtual machine and run the lssam
command. The following sample output is for the Central Server 2 cluster:
Online IBM.ResourceGroup:central-services-2-rg Nominal=Online
|- Online IBM.Application:bpm
|- Online IBM.Application:bpm:cil021029163
- Online IBM.Application:bpm:cil021029164
|- Online IBM.Application:haproxy
|- Online IBM.Application:haproxy:cil021029163
- Offline IBM.Application:haproxy:cil021029164
|- Online IBM.Application:ihs
|- Online IBM.Application:ihs:cil021029163
- Offline IBM.Application:ihs:cil021029164
|- Online IBM.Application:keystone
|- Online IBM.Application:keystone:cil021029163
- Online IBM.Application:keystone:cil021029164
|- Online IBM.Application:sar_agent
|- Online IBM.Application:sar_agent:cil021029163
- Online IBM.Application:sar_agent:cil021029164
|- Online IBM.ResourceGroup:ui-rg Nominal=Offline
|- Online IBM.Application:horizon
|- Online IBM.Application:horizon:cil021029163
- Online IBM.Application:horizon:cil021029164
|- Online IBM.Application:pcg
- Online IBM.Application:pcg:cil021029163
- Online IBM.Application:scui
|- Online IBM.Application:scui:cil021029163
- Online IBM.Application:scui:cil021029164
- Online IBM.ServiceIP:cs2-ip
|- Online IBM.ServiceIP:cs2-ip:cil021029163
- Offline IBM.ServiceIP:cs2-ip:cil021029164
Online IBM.Equivalency:cs2-network-equ
|- Online IBM.NetworkInterface:eth0:cil021029163
- Online IBM.NetworkInterface:eth0:cil021029164

If a resource is not in the correct state (either offline or online), check the actual
state of the service:

192

IBM Cloud Orchestrator 2.4.0.2: User's Guide

1. Log on, as a root user, to the virtual machine where the service runs. The host
name of the VM is listed in the GUI or in the lssam output as property of the
resource.
2. Run the following command:
service <service> status

Tip: The service registered in init.d might differ from the name of the
application resource in System Automation for Multiplatforms.
The output should match the state in the lssam command output.
3. If a service is in an error state or in unknown state, try to manually recover the
service by running the following command on the virtual machine where the
service should run:
Important: If the service is an active/standby service, run this command on
only one of the virtual machines of the cluster.
service <service> stop; service <service> start

For some services, you might encounter the following error situations:
v <name of service> dead but subsys locked: Manually start the service again.
This recovers the service and correctly sets the status to started.
v <name of service> dead but pid file exists: Manually stop the service again.
This deletes the pid file and correctly sets the status of the service to
stopped. If this does not help, delete the pid file manually.
4. If the service does not start, check the log files of the service and correct any
problems found there.
5. You might need to suspend the automation to resolve an error condition. In a
normal state, the automation automatically restarts a service even if the service
is stopped manually. To suspend the automation, log on to one of the cluster
virtual machines and run the following command:
samctrl -M t

After the error condition is resolved, start the service and verify the correct
status. If the status is correct, run the following command to resume the
automation:
samctrl -M f

6. If the resource is still in error, run the following command to reset the resource
in System Automation for Multiplatforms:
resetrsrc -s Name == "<service>" IBM.Application

Managing the placement of services

During a system failure, certain services are moved in the cluster. To identify
where a service is running, use the lssam command. If a service is configured as
active/standby, the command output shows that the server where the service is
running is online, and the standby server is offline. For maintenance or certain
recoveries, you might need to manually move a service in the cluster. You can
move a service by running the following command on one of the servers in the
cluster:
rgreq -n <fqdn_of_the_node_to_be_moved_from> -o move <name_of_resource_group_for_service>

Chapter 2. Installing

193

Troubleshooting agentless adapter controlled services

If an agentless adapter resource is in error, complete the following steps:
1. Log on to the System Automation Application Manager web user interface:
<SAAM_server_hostname>:16311/ibm/console/

Specify the user and password that you defined during the installation. The
default user is eezadmin.
2. Click the Explore Automation Domains tab. Expand the SCOsaam end-to-end
automation policy.
3. Find the automation domain for the resource that is in error, and select this
domain. The right pane shows the resources of this automation domain.
4. Right-click on the resource that is in error, and click Reset. After some time, the
screen refreshes: if the resource recovered from the error, the resource is
working correctly.
5. To understand the cause of the problem, check the log files. Right-click on the
automation domain, and click View Log.
6. If the resource cannot recover from the error, log on to the server where the
service is running. Check the status of the service in the context of the saamuser
user by running the following command:
su saamuser -c "/opt/IBM/tsamp/eez/scripts/servicectrl.sh <service> status; echo $?"

This command returns a System Automation Application Manager type return

code. Check the error cause and correct it manually.

Using /etc/hosts
If the /etc/hosts file is used for System Automation Application Manager to
resolve the host name of the IBM Cloud Orchestrator servers, you must restart
System Automation Application Manager after each change in the /etc/hosts file
to allow System Automation Application Manager to use the changes.

Suspending automation for a resource or a resource group for

manual interaction
If you need to manually interact with an IBM Cloud Orchestrator management
stack resource or resource group, you must stop the System Automation
Application Manager automation to ensure that System Automation Application
Manager does not try to bring the resource to the desired state. For example, if you
are upgrading the product or installing a fix, you might need to start and stop a
resource. To suspend the System Automation Application Manager automation,
complete the following steps:
1. Log on to the System Automation Application Manager web user interface:
<SAAM_server_hostname>:16311/ibm/console/

Specify the user and password that you defined during the installation. The
default user is eezadmin.
2. Click the Explore Automation Domains tab. Expand the SCOsaam end-to-end
automation policy.
3. In the Resources section in the right pane, expand the list of resources and
resource groups.
4. Right-click the resource or resource group for which you want to temporarily
suspend the System Automation Application Manager automation, and click

194

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Suspend Automation.... In the displayed window, click Submit. The resource

or the resource group and all the resources in the group are excluded from the
System Automation Application Manager automation.
5. After you finish manually interacting with the resource or the resource group,
resume the automation by clicking Resume Automation. System Automation
Application Manager brings the resource or the resource group to the desired
state.

Upgrade fails with a DB2 error

The upgrade to IBM Cloud Orchestrator 2.4 or to IBM Cloud Orchestrator 2.4.0.x
fails with a DB2 error.
The following error is displayed:
"Ran su - db2inst1 -c "(db2 connect to openstac)
&& (db2 connect reset)" returned 4"

&& (db2 grant dbadm on database to user dash)

Reason:
DB2 passwords with special characters might fail as follows:
[2014-12-13 04:22:12,676] 172.16.144.201 [2014-12-13T04:22:12+00:00] ERROR: Exception handlers
complete
[2014-12-13 04:22:12,676] 172.16.144.201 [2014-12-13T04:22:12+00:00] FATAL: Stacktrace dumped
to /var/chef/cache/chef-stacktrace.out
[2014-12-13 04:22:12,676] 172.16.144.201 Chef Client failed. 40 resources updated
in 557.027162241 seconds
[2014-12-13 04:22:12,701] 172.16.144.201 [2014-12-13T04:22:12+00:00] ERROR:
db2_user[create database user] (sco23-upgrade::upgrade-create-central-os-db line 75) had an error:
Mixlib::ShellOut::ShellCommandFailed: execute[grant privilege to user(dash) on database(openstac)]
(/var/chef/cache/cookbooks/db2/providers/user.rb line 43) had an error:
Mixlib::ShellOut::ShellCommandFailed: Expected process to exit with [0], but received 4
[2014-12-13 04:22:12,701] 172.16.144.201 ---- Begin output of su - db2inst1 -c
"(db2 connect to openstac) && (db2 grant dbadm on database to user dash)
&& (db2 connect reset)" ---[2014-12-13 04:22:12,702] 172.16.144.201 STDOUT: SQL5035N
to the current release.

The database must be upgraded

[2014-12-13 04:22:12,702] 172.16.144.201 SQLSTATE=55001

[2014-12-13 04:22:12,702] 172.16.144.201 STDERR:
[2014-12-13 04:22:12,702] 172.16.144.201 ---- End output of su - db2inst1 -c
"(db2 connect to openstac) && (db2 grant dbadm on database to user dash)
&& (db2 connect reset)" ---[2014-12-13 04:22:12,703] 172.16.144.201 Ran su - db2inst1 -c "(db2 connect to openstac)
(db2 grant dbadm on database to user dash) && (db2 connect reset)" returned 4

&&

[2014-12-13 04:22:12,747] 172.16.144.201 [2014-12-13T04:22:12+00:00]

FATAL: Chef::Exceptions::ChildConvergeError: Chef run process exited unsuccessfully (exit code 1)

Solution:
1. Rollback to the existing system before starting the upgrade. Extract the IBM
Cloud Orchestrator package.
2. Back up <ICO_PACKAGE_PATH>/data/installer/chef-repo/cookbooks/db2upgrade/recipes/db2-upgrade.rb before editing as follows:
a. Add the line
Chapter 2. Installing

195

require shellwords

before the existing line:

DB2_DIR = node[db2][inst_dir] + V + node[db2][version]

b. Update the line:

node.override[db2][instance_password] = get_password user, node[db2][instance_username]

to the following line:

node.override[db2][instance_password] = Shellwords.escape(get_password user, node[db2]
[instance_username])

3. Continue installing the Deployment Service.

Troubleshooting upgrade
Use these tips to ensure that the upgrade succeeds.

Investigating an upgrade failure

If a problem occurs during the job-update process and the job status is WARNING or
ERROR, you can troubleshoot the problem as follows:
1. To review the job details and the related error message, run the following
command:
ds job-show job_ID

2. Review the /var/log/ds/ds-engine-job_ID.log log files.

3. If possible, fix the issue and rerun the upgrade.
4. If the job is not recoverable, complete the following steps:
a. If the Central Server upgrade job failed, roll back all Central Servers. You do
not need to roll back the Region Servers because the Region Server upgrade
job does not run until the Central Server upgrade job finishes successfully.
b. If the Central Server upgrade job finished successfully, but a Region Server
upgrade job failed, roll back the affected Region Server.
c. Fix the issue.
d. Rerun the upgrade.

Upgrade fails because of incorrect configuration

Problem
The upgrade job fails because of incorrect configuration in the upgrade
configuration file.
Solution
Roll back the IBM Cloud Orchestrator servers, correct the configuration, and rerun
the ico-upgrade-tool command.
1. Roll back the IBM Cloud Orchestrator Servers:
a. If the Central Server upgrade job failed, roll back all Central Servers. You do
not need to roll back the Region Servers because the Region Server upgrade
job does not execute until the Central Server upgrade jobs are finished
successfully.

196

IBM Cloud Orchestrator 2.4.0.2: User's Guide

b. If the Central Server upgrade job is finished successfully, but the Region
Server upgrade jobs failed due to incorrect configuration in the upgrade
configuration file, roll back the Region Servers that failed to run the
upgrade jobs.
2. Edit the upgrade configuration file to provide the correct information, as
described in Configuring the upgrade configuration file on page 158.
3. Run the following command to rerun the failed upgrade jobs:
ico-upgrade-tool upgrade -C CENTRAL_SRV1_IP -p CENTRAL_SRV1_ROOT_PASS

The ico-upgrade-tool command bypasses the finished upgrade jobs.

4. Check the job status to make sure that the upgrade job finished successfully.

Upgrade fails because of an unresponsive Compute Node

It is possible to disassociate a Compute Node from a region on the Deployment
Server performing the following steps:
v Log on to your Deployment Server.
v Find the failing node using the command ds node-list.
v Run the command ds job-disassociate-node -N nodeID (this node will still
appear in the node list with status free).
v Run the upgrade for the KVM region again.
v Associate the node back to your region running the command ds
job-associate-node -N compute=freeComputeNodeID regionID.

VMware region failed to start nova-network after upgrade

Problem
nova-network failed to start after upgrade, and the following error is displayed:
nova.openstack.common.threadgroup
Stderr: "iptables-restore v1.4.7: host/network `None not found
Error occurred at line: 27
Try `iptables-restore -h or iptables-restore --help for more information."

Solution
1. Back up the /etc/sysconfig/iptables file.
2. Clean iptables by running the following command:
iptables -F && iptables -t nat -F
service iptables save

3. Restart the nova network service for the special cluster. For example, if your
cluster name is sco-cluster-01, restart the nova network service by running the
following command:
service openstack-nova-network-sco-cluster-01 restart

4. Check the backup file for additional rules that must be added manually.

PATTERNS submenus are not displayed correctly after upgrade

Problem
After you upgrade to IBM Cloud Orchestrator 2.4, if you use the same browser
session as before the upgrade, the PATTERNS submenus are not displayed
correctly.

Chapter 2. Installing

197

Solution
Clear your browser cache, and restart your browser.

Cinder volume does not work correctly after upgrade

Problem:
After SmartCloud Orchestrator 2.3 is upgraded to IBM Cloud Orchestrator 2.4, the
existing SmartCloud Orchestrator 2.3 Cinder volumes do not work, or the
following error is displayed in the compute.log file, if you try to attach the Cinder
volumes to instances:
"ProcessExecutionError: Unexpected error while running command.\nCommand:
sudo nova-rootwrap /etc/nova/rootwrap.conf iscsiadm -m node -T iqn.201010.org.openstack:volume-7d3c3cf5-d904-4bf0-aa37-b27673a71085 -p 172.16.144.206:3260
--rescan\nExit code: 21\nStdout: \nStderr: iscsiadm: No session found.\\n\n"]

Solution:
Use following shell script to fix your problem:
#!/bin/bash
if (pgrep tgtd > /dev/null 2>&1); then tgtd_ids=`pgrep tgtd`
for i in $tgtd_ids;do
kill -9 $i done
fi
service tgtd restart

Installation reference
Advanced users can customize the installation to suit site-specific needs.

Command-line methods
If you do not want to use the GUI method to install, you can use the CLI method
instead.

Using the command-line interface to deploy IBM Cloud

Orchestrator
You can use the command-line interface to deploy your IBM Cloud Orchestrator
environment.
Before registering the nodes, you must prepare a virtual machine or physical
machine that has Red Hat Enterprise Linux installed and SSH enabled.
The deployment is done in two steps:
1. Register the nodes as described in Registering the nodes on page 199. In the
Deployment Service, define the specifications of the nodes to build the defined
topology, such as the node IP address, the user to be used to connect to the
node and the related password, the port to be used by the SSH protocol, the
name of the network interface, and all the parameters that do not have a
default value or for which you want to change the default value.
2. Deploy the environment as described in Running the deployment on page
200. The IBM Cloud Orchestrator components are installed according to the
topology that you chose.
After the initial deployment, you can add Region Servers to your environment as
described in Deploying a Region Server on page 45.

198

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Registering the nodes

To register a node in the Deployment Service database, run the ds node-create
command on the Deployment Server. You can specify the following parameters:
Address
The IP address or FQDN of the node. This parameter is optional if the Fqdn
parameter is specified. . If the IP address is not specified, the FQDN is
used to connect to the node. If the Fqdn parameter is specified and the
Address parameter is specified with an IP address, the <Fqdn, IP address>
entry is added into the /etc/hosts file for the DNS service. If you are
using Corporate DNS, make sure that the IP address of the node is able to
be resolved by DNS and it is the same as the FQDN that you specified. To
check if the node is registered in the Corporate DNS, you can use the host
<ip-addr> command to check that the correct FQDN of the node is
returned.
Fqdn

The FQDN of the node. This parameter is optional if the Address

parameter is specified. If the FQDN is not specified, the installer tries to
retrieve it automatically according to the specified address.

Port

The SSH port to access the node. This parameter is required.

ServiceAddress
The service IP address for DB2. This parameter is optional.
Note: This is a mandatory requirement if you want to move your database
on a different system at a later time. For information about moving the
database, see Move the database to an external system on page 84.
User

The user name to access the node via SSH. The user must be the root user
or must have sudo privilege. This parameter is required.

Password
The password used to access the node. This parameter is optional if the
KeyFile parameter is specified. The password can contain only the
following characters:
a-zA-Z0-9!()-.?[]

KeyFile
The key file location used to access the node. This parameter is optional if
the Password parameter is specified.
To understand the number of nodes that are required in the selected topology, can
use ds template-resource-list <template_UUID> command.
For example, if you deploy an environment by using the sco-allinone-kvm
template, you must run the following commands on the Deployment Server:
source keystonerc; ds template-list
...
| b779f01e-95d6-4ca6-a9ec-a37753f66a2b | sco-allinone-kvm
| SCO Core + additional KVM compute node deployment (Existing machines)| ACTIVE
| 2014-03-27T01:30:54.661581 | 2014-03-27T06:58:35.211096 |
...
ds template-resources-list b779f01e-95d6-4ca6-a9ec-a37753f66a2b
+---------+------------------+-----------------------------+-----------+
| name
| type
| run_list
| run_order |
+---------+------------------+-----------------------------+-----------+
| control | Existing Machine | role[sco-allinone-kvm-mgm] | 1
|

Chapter 2. Installing

199

| compute | Existing Machine | role[kvm-compute]

| 2
|
| iwd
| Existing Machine | role[iwd]
| 3
|
+---------+------------------+-----------------------------+-----------+
ds node-create -t "IBM::SCO::Node" -p "{Address: 192.0.2.211, Port: 22, User: root,
Password: password, Fqdn: sco-core.example.com }" sco-core
ds node-create -t "IBM::SCO::Node" -p "{Address: 192.0.2.212, Port: 22, User: root,
Password: password, Fqdn: sco-iwd.example.com}" sco-iwd
ds node-create -t "IBM::SCO::Node" -p "{Address: 192.0.2.213, Port: 22, User: root,
Password: password,Fqdn: sco-region.example.com }" kvm-compute

where sco-core, sco-iwd, and kvm-compute are the node names that you assign to
each node. It is recommended to assign names that are related to the role of the
node.
Some templates may include Resource Reference type resource which refers to an
existing Resource. For example:
ds template-resources-list fc11c554-24d4-4bba-a891-990aeee1f310
+--------------------+--------------------+--------------------------+-----------+
| name
| type
| run_list
| run_order |
+--------------------+--------------------+--------------------------+-----------+
| central_server_1
| Existing Machine
| role[central-server-1]
| 1
|
| central_server_2
| Existing Machine
| role[central-server-2]
| 2
|
| central_server_3
| Existing Machine
| role[central-server-3]
| 3
|
| cs1_ico_agents_all | Resource Reference | role[ico_mon_agents_all] | 4
|
| cs2_ico_agent_sar | Resource Reference | role[ico_mon_agent_sar] | 5
|
| cs3_ico_agent_sar | Resource Reference | role[ico_mon_agent_sar] | 6
|
+--------------------+--------------------+--------------------------+-----------+

It is not needed to associate the node with this kind of resource when creating job.
Otherwise, an error will be reported.
You can verify that the node registration completed successfully by using the
following command:
ds node-list
+--------------------------------------+---------------+----------------+------+-------| id
| name
| address
| user | status
+--------------------------------------+---------------+----------------+------+-------| 9992bd06-0ae2-460b-aedb-0259a8acca70 | sco-core
| 192.0.2.211
| root | FREE
| e5b6d881-1aa6-4ac0-824f-d48c296eae23 | kvm-compute | 192.0.2.213
| root | FREE
| f80f622c-e7a5-40c2-be17-9c7bd60a0142 | sco-iwd
| 192.0.2.212
| root | FREE
+--------------------------------------+---------------+----------------+------+-------+----------------------------+----------------------------+
| created_at
| updated_at
|
+----------------------------+----------------------------+
| 2014-04-09T09:35:58.397878 | 2014-04-10T02:44:31.100993 |
| 2014-04-09T09:36:16.651048 | 2014-04-10T02:44:31.110808 |
| 2014-04-09T09:36:40.692384 | 2014-04-10T02:44:31.116846 |
+----------------------------+----------------------------+

Running the deployment

Run the following steps:
1. In the Deployment Service, register the deployment job by running the ds
job-create command. For example:
ds job-create -t #{template_id}
-P "MGMNetInterface=#{net_interface};SingleSignOnDomain=#{domain_name}"
-N "control=#{sco-core-id};iwd=#{sco-iwd-id};compute=#{kvm-compute-id}\"
myallinonekvm

200

IBM Cloud Orchestrator 2.4.0.2: User's Guide

where
v template_id is the ID of the sco-allinone-kvm template that you can get by
using the ds template command.
v net_interface is the NIC device that must be the same in each node.
v SingleSignOnDomain is the DNS domain name where the manage-from
components are installed.
v sco-core-id, sco-iwd-id, and kvm-compute-id are the IDs that you can get by
using the ds node-list command.
v myallinonekvm is the name you choose to identify the job.
Note: In the Deployment Service commands, use double quotation marks to
specify parameter values. Passwords can contain only the following characters:
a-zA-Z0-9!()-.?[]

Spaces and hyphens are not allowed. Use leading and trailing single quotation
marks (') when special characters are used within a password, as shown in the
following example:
ds node-create -t "IBM::SCO::Node" -p "{Address: 192.0.2.211, Port: 22, User: root,
Password: pass_w0rd, Fqdn: sco-core.example.com }" sco-core

If a problem occurs during job creation and the job status is WARNING or ERROR,
run the ds job-show <job ID> command to inspect the details of the job which
also include the related error message.
2. To perform the installation, execute the deployment job by running the
following command, for example:
ds job-execute myallinonekvm

where myallinonekvm is the name to identify the job that you specified in the
previous step.
3. Use the ds job-list command to check the status of the job.
4. If you do not create a job correctly and you want to delete the job, use the ds
job-delete command.
ds job-delete job_id

5. When the status of the job is FINISHED, the deployment is complete.

Deploying a Region Server (CLI method)

If you do not want to use the Deployment Service wizard, you can use the
command-line interface to deploy a Region Server in your IBM Cloud Orchestrator
environment.

Before you begin

Verify that the Deployment Server and the Central Servers are ready in your
environment. For more information about installing the Deployment Server and
the Central Servers, see Installing the Deployment Service on page 34 and
Deploying the Central Servers on page 44.
VMware only: Do not install more than one IBM Cloud Orchestrator instance on
the same vCenter environment if the instances have access to the same resources.
Each IBM Cloud Orchestrator instance must use a different userid to access the
vCenter. The intersection between the resources that are seen by these users (for
example, clusters, datastore) must be empty.

Chapter 2. Installing

201

PowerVC only
Ensure that the PowerVC server has been installed.
Note: Using a PowerVC server that has been configured for both Shared
Storage Pools and SAN-fabric managed Storage is not recommended. If
possible, use two PowerVC servers, each configured for using a single
Storage Type, and two PowerVC Region Servers (including two PowerVC
Neutron Servers) to manage them.
Note: PowerVC must be at version 1.2.1.2 and you must also apply the
interim fix shipped with IBM Cloud Orchestrator. For more information,
see Applying interim fix 1 to PowerVC 1.2.1.2 on page 50.
z/VM only
You must enable the xCAT version that is provided with z/VM 6.3. To
enable xCAT for z/VM 6.3, follow chapters 1-4 in the Enabling z/VM for
OpenStack (Support for OpenStack Icehouse Release) guide, at
http://www.vm.ibm.com/sysman/openstk.html.

About this task

The deployment procedure is the same as described in Using the command-line
interface to deploy IBM Cloud Orchestrator on page 198 except that when
deploying the Region Server, you must specify the job ID of the Central Server.
If you are not sure which deployment template to use, choose the
vmware_region_neutron template. The vmware_region_neutron template is used in
the examples in this procedure.

Procedure
1. Check that the prerequisite job to install the Central Servers completed
successfully.
a. Use the ds job-list command to display the job details. The status of the
job should be FINISHED.
Example:
source ~/openrc
ds job-list

Example output:
+--------------------------------------+---------------+----------+-----------------------| id
| name
| status | pjob_id
+--------------------------------------+---------------+----------+-----------------------| 103cbe78-3015-4c7c-b02b-8de9d051ad1d | centralsrvjob | FINISHED |
+----------------------------+----------------------------+
| created_at
| updated_at
|
+----------------------------+----------------------------+
| 2014-08-13T03:41:46.237133 | 2014-08-13T05:57:25.009566 |

b. Make a note of the job ID.

In this example, the job ID is 103cbe78-3015-4c7c-b02b-8de9d051ad1d.
2. Choose the deployment template.
a. Use the ds template-list command to display a list of templates.
To display a list of all templates, run the following command:
ds template-list

To list the templates for a particular hypervisor, run the following

command:
ds template-list | grep hypervisor

202

IBM Cloud Orchestrator 2.4.0.2: User's Guide

where hypervisor is one of the following values: hyperv, kvm, power, vmware,
or zvm.
Example:
ds template-list | grep vmware

Example output:
...
| e9467b25-fc7f-4d0b-ab4d-fb052768a9fc | vmware_region_neutron
| VMware region-server deployment with Neutron network.
...

b. Identify the template ID for the chosen template. The template ID is

displayed in the output of the ds template-list command.
In this example, the template ID is e9467b25-fc7f-4d0b-ab4d-fb052768a9fc.
3. Identify the resources that are used by the template. Use the ds
template-resources-list command, as follows:
ds template-resources-list template_id

Example:
ds template-resources-list e9467b25-fc7f-4d0b-ab4d-fb052768a9fc

Example output:
+----------------------+--------------------+------------------------------------------+-----------+
| name
| type
| run_list
| run_order |
+----------------------+--------------------+------------------------------------------+-----------+
| vmware_region_server | Existing Machine | role[vmware-region],role[vmware-compute] | 1
|
| neutron_network_node | Existing Machine | role[neutron-network-node]
| 2
|
| vrs_ico_agents_sar | Resource Reference | role[ico_mon_agent_sar]
| 3
|
| nnn_ico_agents_sar | Resource Reference | role[ico_mon_agent_sar]
| 4
|
+----------------------+--------------------+------------------------------------------+-----------+

In this example, the template resources are vmware_region_server and

neutron_network_node.
4. Create the required nodes.
a. Create a node for each resource that you identified in the previous step. Use
the ds node-create command.
Example:
ds node-create -t IBM::SCO::Node \
-p {Address: 192.0.2.254, Port: 22, User: root, Password: password } \
vmwareregion
ds node-create -t IBM::SCO::Node
-p {Address: 192.0.2.253, Port: 22, User: root, Password: password } \
vmwareneutron

In this example, the vmwareregion node (the VMware Region Server) is

created for the vmware_region_server resource, and the vmwareneutron node
(the Neutron Server) is created for the neutron_network_node resource.
b. For each node that you created in the previous step, identify the node ID.
The node ID is displayed in the output of the ds node-list command.
Example:
ds node-list

Example output:
+--------------------------------------+---------------+----------------+-------| id
| name
| type
| status
+--------------------------------------+---------------+----------------+-------| 0be0d025-8637-4ec9-a51d-a8b1065aae72 | vmwareregion | IBM::SCO::Node | INUSE
| bfb2a2cc-dc4f-4c43-ae8f-be07567f3e19 | vmwareneutron | IBM::SCO::Node | INUSE
| 5d9f4dd8-683f-43ce-9861-186336414d70 | central3
| IBM::SCO::Node | INUSE
| 69926d1c-b57b-453b-9c92-b0bbd202d750 | central1
| IBM::SCO::Node | INUSE
| 7dbd222f-d20a-4bd8-8f3e-77fb66067520 | central2
| IBM::SCO::Node | INUSE
+--------------------------------------+----------------------+---------------------------| job_id
| resource
| created_at
+--------------------------------------+----------------------+----------------------------

Chapter 2. Installing

203

|
|
|
|
|

11dae147-86a0-498e-87d3-46146e687bde
11dae147-86a0-498e-87d3-46146e687bde
103cbe78-3015-4c7c-b02b-8de9d051ad1d
103cbe78-3015-4c7c-b02b-8de9d051ad1d
103cbe78-3015-4c7c-b02b-8de9d051ad1d

|
|
|
|
|

vmware_region_server
neutron_network_node
central_server_3
central_server_1
central_server_2

|
|
|
|
|

2014-08-13T03:41:41.400463
2014-08-13T03:41:41.993816
2014-08-13T03:41:38.865586
2014-08-13T03:41:37.574286
2014-08-13T03:41:38.233124

+----------------------------+
| updated_at
|
+----------------------------+
| 2014-08-13T05:57:37.564439 |
| 2014-08-13T05:57:37.552176 |
| 2014-08-13T03:41:46.279254 |
| 2014-08-13T03:41:46.286440 |
| 2014-08-13T03:41:46.269587 |

In this example, the vmwareregion node ID is 0be0d025-8637-4ec9-a51da8b1065aae72, and the vmwareneutron node ID is bfb2a2cc-dc4f-4c43-ae8fbe07567f3e19.
5. Create a job to install the nodes that you created in the previous step.
a. Use the ds job-create command.
The parameters that you specify in the ds job-create command are
hypervisor-specific. For more information about the parameters required for
each hypervisor, see Hypervisor-specific information when deploying a
Region Server (CLI method) on page 205.
Example:
ds job-create -t e9467b25-fc7f-4d0b-ab4d-fb052768a9fc \
-P "MGMNetInterface=eth0;VMServerHost=203.0.113.0; \
VMServerPassword=vmserver_password;VMServerUserName=vmserver_user; \
VMDataStoreName=vm_datastore;VMClusterName=vm_cluster" \
-N "vmware_region_server=0be0d025-8637-4ec9-a51d-a8b1065aae72; \
neutron_network_node=bfb2a2cc-dc4f-4c43-ae8f-be07567f3e19" \
-p 103cbe78-3015-4c7c-b02b-8de9d051ad1d \
vmware-region-server-neutron

Example output:
+--------------------------------------+------------------------------+---------| id
| name
| status
+--------------------------------------+------------------------------+---------| 11dae147-86a0-498e-87d3-46146e687bde | vmware-region-server-neutron | CREATED
+--------------------------------------+----------------------------+----------------------------+
| pjob_id
| created_at
| updated_at
|
+--------------------------------------+----------------------------+----------------------------+
| 103cbe78-3015-4c7c-b02b-8de9d051ad1d | 2014-08-13T05:57:37.378651 |
|

If you want to deploy a Region Server with shared database mode (that is,
the Region Server uses the database that is deployed in the Central Server),
you must include the following additional parameters in the -P option of
the ds job-create command:
ComputeDBUsername=compute_database_user
DashboardDBUsername=dashboard_database_user
ImageDBUsername=image_database_user
MeteringDBUsername=metering_database_user
NetworkDBUsername=network_database_user
OrchestrationDBUsername=orchestration_database_user
VolumeDBUsername=volume_database_user

b. Make a note of the job ID.

In this example, the job ID is 11dae147-86a0-498e-87d3-46146e687bde.
If a problem occurs during job creation and the job status is WARNING or
ERROR, run the following command to inspect the details of the job and the
related error message:
ds job-show job_id

6. Run the job. Use the ds job-execute command, as follows:

ds job-execute job_id

Example:

204

IBM Cloud Orchestrator 2.4.0.2: User's Guide

ds job-execute 11dae147-86a0-498e-87d3-46146e687bde

Results
The Region Server, and the Neutron Server if specified, is deployed.
Hypervisor-specific information when deploying a Region Server (CLI method):
When you use the command-line interface to deploy a Region Server, some of the
information that you must specify is hypervisor-specific.
Hyper-V
If you use one of the Hyper-V templates, you must create nodes for the Hyper-V
Region Server and the Neutron Server.
Example:
ds node-create -t IBM::SCO::Node \
-p {Address: 192.0.2.254, Port: 22, User: root, Password:password } \
hypervregion
ds node-create -t IBM::SCO::Node
-p {Address: 192.0.2.253, Port: 22, User: root, Password:password } \
hypervneutron

In this example, the hypervregion node (the Hyper-V Region Server) is created for
the hyperv_region_neutron resource, and the hypervneutron node (the Neutron
Server) is created for the neutron_network_node resource.
To create a job to install the Hyper-V Region Server and the Neutron Server, run
the following command:
ds job-create -t template_id \
-P "MGMNetInterface=net_interface" \
-N "hyperv_region_neutron=hyperv_region_node_id; \
neutron_network_node=neutron_network_node_id" \
-p central_server_job_id \
hyperv-region-server-neutron

where
template_id
The template ID can be identified from the output of the ds template-list
command. Find the relevant template name in the name column (for
example, hyperv_region_neutron), and identify the corresponding ID in the
id column.
net_interface
You must specify the same NIC device (for example, eth0) in each node.
hyperv_region_node_id
The Region Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, hypervregion), and identify the corresponding ID in the id
column.
neutron_network_node_id
The Neutron Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, hypervneutron), and identify the corresponding ID in the id
column.
Chapter 2. Installing

205

central_server_job_id
The job ID for the Central Servers deployment can be identified from the
output of the ds job-list command. Find the relevant job name in the
name column (for example, sco-central-servers), and identify the
corresponding ID in the id column.
KVM
If you use one of the KVM templates, you must create nodes for the KVM Region
Server, the Neutron Server (if using Neutron network), and the KVM Compute
Node.
Example:
ds node-create -t "IBM::SCO::Node" \
-p "{Address: 192.0.2.219, Port: 22, User: root, Password: password }"
kvm-region
ds node-create -t "IBM::SCO::Node" \
-p "{Address: 192.0.2.220, Port: 22, User: root, Password: password }"
kvm-network-node
ds node-create -t "IBM::SCO::Node" \
-p "{Address: 192.0.2.221, Port: 22, User: root, Password: password }"
kvm-compute

In this example, the kvm-region node (the KVM Region Server) is created for the
kvm_region_neutron resource, the kvm-network-node node (the Neutron Server) is
created for the neutron_network_node resource, and the kvm-compute node (the
KVM Compute Node) is created for the kvm_compute resource.
To create a job to install the KVM Region Server, the Neutron Server, and the KVM
Compute Node, run the following command:
ds job-create -t template_id \
-P "MGMNetInterface=net_interface" \
-N "kvm_region_neutron=kvm_region_id; \
neutron_network_node=kvm_network_node_id; \
kvm_compute=kvm_computeIid" \
-p central_server_job_id \
kvm-region-server-neutron

Example with Neutron Server and shared database:

ds job-create -t fbf9b885-2f72-4da6-930b-44f792925e29 \
-P "MGMNetInterface=eth0;ComputeDBUsername=nova2; \
DashboardDBUsername=dash2;ImageDBUsername=glance2; \
MeteringDBUsername=ceil2;NetworkDBUsername=neutron2; \
OrchestrationDBUsername=heat2;VolumeDBUsername=cinder2" \
-N "kvm_region_neutron=e76db559-2605-4e68-b69b-4de89ccdedb5; \
neutron_network_node=d1283443-f62c-4a1c-96f7-eb6dcc7c90ec; \
kvm_compute=874ec747-ccb0-4057-bbe5-8868bd5902d4"
\
-p e76db559-2605-4e68-b69b-4de89ccdedb5 \
kvm-region-server-neutron

If you want to add additional compute nodes to your environment, see Scaling
out a deployed environment on page 144.
PowerVC
If you use one of the PowerVC templates, you must create nodes for PowerVC
Region Server and the Neutron Server.

206

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Example:
ds node-create -t IBM::SCO::Node \
-p {Address: 192.0.2.15, Port: 22, User: root, Password:password, Fqdn: PVCRS.69.customer.ibm.com} \
powervc_region_server
ds node-create -t IBM::SCO::Node
-p {Address: 192.0.2.16, Port: 22, User: root, Password:password, Fqdn: PVCNS.69.customer.ibm.com} \
neutron_network_node

In this example, the powervc_region_server node (the PowerVC Region Server) is

created for the powervc_region_server resource, and the neutron_network_node
node (the Neutron Server) is created for the neutron_network_node resource.
To create a job to install the PowerVC Region Server and the Neutron Server, run
the following command:
Example:
ds job-create -t 1d8ef566-4eb2-4445-bafa-28eb2461bc06 \
-P "PVCServer=192.0.2.22;PVCServerUser=admin; \
PVCServerPassword=passw0rd;PVCQpidPassword=passw0rd; \
MGMNetInterface=eth0;ComputeDBUsername=nova3; \
DashboardDBUsername=dash3;ImageDBUsername=glance3; \
MeteringDBUsername=ceil3;NetworkDBUsername=neutron3; \
OrchestrationDBUsername=heat3;VolumeDBUsername=cinder3" \
-N "powervc_region_server=e76db559-2605-4e68-b69b-4de89ccdedb5; \
neutron_network_node=d1283443-f62c-4a1c-96f7-eb6dcc7c90ec" \
-p e76db559-2605-4e68-b69b-4de89ccdedb5 \
power-region-server-neutron

where
template_id
The template ID can be identified from the output of the ds template-list
command. Find the relevant template name in the name column (for
example, powervc_region_neutron), and identify the corresponding ID in
the id column.
net_interface
You must specify the same NIC device (for example, eth0) in each node.
PVCServer
This mandatory parameter specifies the location of the PowerVC server.
PVCServerUser
This mandatory parameter specifies the root user of the PowerVC server.
PVCServerPassword
This mandatory parameter specifies the root password for the PowerVC
server.
PVCQpidPassword
This mandatory parameter specifies the qpid password for the PowerVC
server.
To find this password, run the following command on the PowerVC server:
cat /opt/ibm/powervc/data/pw.file

powervc_region_node_id
The Region Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, powervc_region_server), and identify the corresponding ID in the
id column.
Chapter 2. Installing

207

neutron_network_node_id
The Neutron Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, neutron_network_node), and identify the corresponding ID in the
id column.
central_server_job_id
The job ID for the Central Servers deployment can be identified from the
output of the ds job-list command. Find the relevant job name in the
name column (for example, sco-central-servers), and identify the
corresponding ID in the id column.
VMware
If you use the VMware templates, you must create nodes for the VMware Region
Server and the Neutron Server (if using Neutron network).
Example:
ds node-create -t IBM::SCO::Node \
-p {Address: 192.0.2.254, Port: 22, User: root, Password:password } \
hypervregion
ds node-create -t IBM::SCO::Node
-p {Address: 192.0.2.253, Port: 22, User: root, Password:password } \
hypervneutron

In this example, the vmwareregion node (the VMware Region Server) is created for
the vmware_region_server resource, and the vmwareneutron node (the Neutron
Server) is created for the neutron_network_node resource.
To create a job to install the VMware Region Server and the Neutron Server, run
the following command:
ds job-create

-t #{template_id} \
-P "MGMNetInterface=#{net_interface};VMServerHost=#{def_vcenter_ip}; \
VMServerPassword=#{def_passwd};VMServerUserName=#{def_user}; \
VMDataStoreName=#{def_data_store};VMClusterName=#{def_cluster_name}" \
-N "vmware_region_server=#{vmware-region-id}; \
neutron_network_node=#{vmware-network-node-id}" \
-p <central-server-job-id> \
vmware-region-server-neutron

where
template_id
The template ID can be identified from the output of the ds template-list
command. Find the relevant template name in the name column (for
example, vmware_region_neutron), and identify the corresponding ID in the
id column.
net_interface
You must specify the same NIC device (for example, eth0) in each node.
VMServerHost
This mandatory parameter specifies the vCenter host IP address.
VMServerUsername
This mandatory parameter specifies the user name that is used to connect
to the vCenter.
VMServerPassword
This mandatory parameter specifies the password for VMServerUsername.

208

IBM Cloud Orchestrator 2.4.0.2: User's Guide

VMDataStoreName
This mandatory parameter specifies the datastore that is used to store the
virtual machine. You can specify a regular expression to match the name of
a datastore. For example, VMDataStoreName="nas.*" selects all datastores
with a name that starts with nas.
VMClusterName
This mandatory parameter specifies the cluster name in vCenter where the
virtual machine is located.
vmware-region-id
The Region Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, vmwareregion), and identify the corresponding ID in the id
column.
vmware-network-node-id
The Neutron Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, vmwareneutron), and identify the corresponding ID in the id
column.
central-server-job-id
The job ID for the Central Servers deployment can be identified from the
output of the ds job-list command. Find the relevant job name in the
name column (for example, sco-central-servers), and identify the
corresponding ID in the id column.
z/VM
If you use one of the z/VM templates, you must create nodes for the z/VM
Region Server and the Neutron Server.
Example:
ds node-create -t IBM::SCO::Node -p {Address: 192.0.2.12, Port: 22, User: root,
Password: passw0rd} rs-zenv1
ds node-create -t IBM::SCO::Node -p {Address: 192.0.2.13, Port: 22, User: root,
Password: passw0rd} ns-zenv1

In this example, the rs-zenv1 node (the z/VM Region Server) is created for the
zvm_region_server resource, and the ns-zenv1 node (the Neutron Server) is created
for the neutron_network_node resource.
To create a job to install the z/VM Region Server and the Neutron Server, run the
following command:
ds job-create -t template_id \
-P "MGMNetInterface=net_interface;" \
-N "zvm_region_neutron=zvm_region_node_id; \
neutron_network_node=neutron_network_node_id" \
-p central_server_job_id \
zvm-region-server-neutron

where
template_id
The template ID can be identified from the output of the ds template-list
command. Find the relevant template name in the name column (for
example, zvm_region_neutron), and identify the corresponding ID in the id
column.
Chapter 2. Installing

209

net_interface
You must specify the same NIC device (for example, eth0) in each node.
zvm_region_node_id
The Region Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, rs-zenv1), and identify the corresponding ID in the id column.
neutron_network_node_id
The Neutron Server node ID can be identified from the output of the ds
node-list command. Find the relevant node name in the name column (for
example, ns-zenv1), and identify the corresponding ID in the id column.
central_server_job_id
The job ID for the Central Servers deployment can be identified from the
output of the ds job-list command. Find the relevant job name in the
name column (for example, sco-central-servers), and identify the
corresponding ID in the id column.
Example:
ds job-create -t abbd039b-e5ee-44bc-b770-6e334272fb14
-N zvm_region_server=303a5d4f-f9bf-4ed5-a1f5-5039b5b057c7;
neutron_network_node=6f3d9608-7942-49a8-887f-8e638a6161d2
-P MGMNetInterface=eth1;DataNetInterface=eth1;ExtNetInterface=eth1;
XcatServer=192.0.2.66
-p 1e593793-3f48-4782-ace5-3ddd8b37289b job-zvm-server

Note:
v If you do not want to use the default parameter value, use the -P option to set
the parameter value, as shown in the following example:
-P MGMNetInterface=eth1;DataNetInterface=eth1;ExtNetInterface=eth1

v Use the -p option to specify the job ID for the parent job that installs the Central
Servers, as shown in the following example:
-p 1e593793-3f48-4782-ace5-3ddd8b37289b

The job ID for the Central Servers deployment can be identified from the output
of the ds job-list command. Find the relevant job name in the name column
(for example, sco-central-servers), and identify the corresponding ID in the id
column.
v For more information about template parameters and how to configure the
parameters, refer to Customizing a z/VM Region Server deployment on page
51.
After you run the ds job-execute command, configure OpenStack as described in
Configuring the non-CMO Node within "Chapter 5. OpenStack Configuration" in the
Enabling z/VM for OpenStack (Support for OpenStack Icehouse Release) guide, at
http://www.vm.ibm.com/sysman/openstk.html.
Note: z/VM Single System Image (SSI) configuration is not supported.

210

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Customizable installation information

IBM Cloud Orchestrator provides several deployment templates and deployment
parameters to enable you to customize your installation.

Deployment templates for demo topology

These deployment templates define the IBM Cloud Orchestrator demo topology.
Table 18. Deployment templates for demo topology
Template
name

Comments

sco-allinonekvm

Installs and configures IBM Cloud Orchestrator management stack together

with a KVM-based region server with one compute node

sco-allinoneVMware

Installs and configures IBM Cloud Orchestrator management stack with a

VMware-based region server. It connects to an existing VMware vCenter.

sco-allinoneextdb

Installs and configures IBM Cloud Orchestrator management stack with an

external database.

sco-devstack

Installs and configures IBM Cloud Orchestrator management stack.

Deployment templates for distributed topology

These deployment templates define the IBM Cloud Orchestrator distributed
topology.
Table 19. Deployment templates for distributed topology
Template name

Role

Managed-to
hypervisor Network

Database
location

sco-central-servers

Central
Servers

hypervisor
agnostic

network
agnostic

Central
Server 1

sco-central-serversextdb

Central
Servers

hypervisor
agnostic

network
agnostic

external
database

hyperv_region-neutron

Hyper-V
Region
Server

Hyper-V

Neutron

Region
Server

hyperv_region-neutronextdb

Hyper-V
Region
Server

Hyper-V

Neutron

external
database

hyperv_region-neutronsharedb

Hyper-V
Region
Server

Hyper-V

Neutron

Central
Server 1

kvm_region-with-compute KVM
Region
Server

KVM

novanetwork

Region
Server

kvm_region-withcompute-extdb

KVM
Region
Server

KVM

Neutron

external
database

kvm_region-withcompute-neutron

KVM
Region
Server

KVM

Neutron

Region
Server

Comments

Cannot use
scocentralserversextdb

Chapter 2. Installing

211

Table 19. Deployment templates for distributed topology (continued)

Managed-to
hypervisor Network

Database
location

kvm_region-withKVM
compute-neutron-sharedb Region
Server

KVM

Neutron

Central
Server 1

Cannot use
scocentralserversextdb

kvm_region-withcompute-sharedb

KVM
Region
Server

KVM

novanetwork

Central
Server 1

Cannot use
scocentralserversextdb

powervc_region_neutron

PowerVC
Region
Server

PowerVC

Neutron

Region
Server

powervc_region_neutron- PowerVC
extdb
Region
Server

PowerVC

Neutron

external
database

powervc_region_neutron- PowerVC
sharedb
Region
Server

PowerVC

Neutron

Central
Server 1

Template name

212

Role

vmware_region

VMware
Region
Server

VMware

novanetwork

Region
Server

vmware_region_neutron

VMware
Region
Server

VMware

Neutron

Region
Server

vmware_region_neutronextdb

VMware
Region
Server

VMware

Neutron

external
database

vmware_region_neutronsharedb

VMware
Region
Server

VMware

Neutron

Central
Server 1

vmware_region-extdb

VMware
Region
Server

VMware

novanetwork

external
database

vmware_region-sharedb

VMware
Region
Server

VMware

novanetwork

Central
Server 1

zvm_region_neutron

z/VM
Region
Server

z/VM

Neutron

Region
Server

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Comments

Cannot use
scocentralserversextdb

Cannot use
scocentralserversextdb

Cannot use
scocentralserversextdb

Table 19. Deployment templates for distributed topology (continued)

Managed-to
hypervisor Network

Database
location

z/VM
Region
Server

z/VM

Neutron

external
database

z/VM
Region
Server

z/VM

Neutron

Central
Server 1

Template name

Role

zvm_region_neutronextdb
zvm_region_neutronsharedb

Comments

Cannot use
scocentralserversextdb

Deployment templates for high-availability distributed topology

These deployment templates define the IBM Cloud Orchestrator high-availability
distributed topology.
Table 20. Deployment templates for high-availability distributed topology
Template name

Role

Managed to
hypervisor Network

Database
location

HA-sco-central-serversextdb

central
servers

hypervisor
agnostic

network
agnostic

external
database

HA-vmware_regionneutron-extdb

VMware
region
server

VMware

neutron

external
database

HA-vmware_regionextdb

VMware
region
server

VMware

novanetwork

external
database

HA-kvm_region-withcompute-neutron-extdb

KVM
region
server

KVM

neutron

external
database

HA-kvm_region-withcompute-extdb

KVM
region
server

KVM

novanetwork

external
database

HA-saam

hypervisor
System
Automation agnostic
Application
Manager
server

network
agnostic

database
agnostic

Comments

Deployment parameters
Check the list of all deployment parameters that you can configure before
deploying IBM Cloud Orchestrator, and the parameter default values.
Table 21. Deployment parameters
Name

Default Value

Description

BPMHome

/opt/ibm/BPM/v8.5

The installation path of Business

Process Manager.
The path can be created or accessed
by the user that deploys IBM Cloud
Orchestrator.

Chapter 2. Installing

213

Table 21. Deployment parameters (continued)

Name

Default Value

Description

CinderStatePath

/var/lib/cinder

The path to save the cinder state.

Make sure that the cinder user can
access the path.

CinderVGSize

100

All the volume size.

Make sure that the Region Server has
enough disk space.

CinderVolumesDir

/var/lib/cinder/volumes

The path to save the volume.

Make sure that the cinder user can
access the path.

DATANetInterface

eth0

The VM data network interface. It is

used only for Neutron networks.

DB2DataDir

/home/db2inst1

The folder to save DB2 data.

The path can be created or accessed
by the user that deploys IBM Cloud
Orchestrator.

DB2DownloadDir

/tmp

The folder to save download binary.

Change it if you do not want to put
the file in /tmp.
The path must exist and must be able
to be written by the user that deploys
IBM Cloud Orchestrator.

DB2ServiceIPNetmask

255.255.255.0

The Netmask of DB2 service IP

address. It is used when you want to
deploy IBM Cloud Orchestrator with
an internal DB2, and give the DB2
node a secondary IP address for the
future to move the DB2 to another
machine.

DiscoveredFlavorPrefix

Onboarded

The prefix that will be added to the

instance name for flavors created for
discovered instances. This parameter
is only for a VMware Region.

DiscoveredVMPrefix

Onboarded

The prefix that will be added to the

name of discovered instances. This
parameter is only for a VMware
Region.

EXTNetInterface

eth0

The external network interface. It is

used only for Neutron networks.

GlanceFileStore

/var/lib/glance/images

The path to save the glance image.

Make sure that the glance user can
access the path.

214

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 21. Deployment parameters (continued)

Name

Default Value

Description

IHSLocalDir

/tmp/ihsinstall

The temporary path for IBM HTTP

Server to save local data.
Change it if you do not want to put
the file in /tmp.
The path must exist and must be able
to be written by the user that deploys
IBM Cloud Orchestrator.

MGMNetInterface

eth0

The interface that is used for

communication between the IBM
Cloud Orchestrator management
components.
It must be consistent on each node.

NetworkManager

nova.network.manager.VlanManager

It is used when you want to deploy a

nova-network based environment or
region.
Keep the value as it is.
In special cases, this may also have
the value of
nova.network.manager.FlatManager.

NovaStatePath

/var/lib/nova

The path to save the nova instances.

Make sure that the nova user can
access the path.

OrchestratorPassword

passw0rd

The password for all of the IBM

Cloud Orchestrator components. The
password can contain only the
following characters:
a-zA-Z0-9_
Important: For security reasons, you
should change the default value.

OSLibvirtType

kvm

The virtualization type for

KVM-based IBM Cloud Orchestrator
deployment.
Change it to qemu if you are using a
virtual machine to deploy. Not
recommended for production.

OSNetworkType

PCGDownloadDir

nova (for non-neutron based

template)
neutron (for neutron-based template)

The network type.

/tmp/pcg

The temporary path for Public Cloud

Gateway to save data.

No need to change it since it is

associated with the template.

Change it if you do not want to put

the file in /tmp.
The path must exist and must be able
to be written by the user that deploys
IBM Cloud Orchestrator.
Chapter 2. Installing

215

Table 21. Deployment parameters (continued)

Name

Default Value

Description

PCGHomeDir

/opt/ibm/pcg

The path for Public Cloud Gateway

to save data.
The path can be created or accessed
by the user that deploys IBM Cloud
Orchestrator.

RegionName

RegionOne (all-in-one)
RegionCentral (multiple region)
RegionKVM (KVM region)
RegionVMware (VMware region)
RegionZVM (z/VM region)
RegionPower (Power region)

This is the region name for

OpenStack. It is important only when
you want to deploy a multiple region
environment.
No need to change it for all-in-one
based template.
In a multiple region environment,
region name must be unique.
You must set the SingleSignOnDomain
parameter value to the DNS domain
name where the manage-from
components are installed. The
manage-from components include
IBM HTTP Server, IBM Cloud
Orchestrator user interfaces,
Workload Deployer, and Business
Process Manager.

SingleSignOnDomain

TSAAMLocal

/tsa

The path for TSA to put data.

The path can be created or accessed
by the user that deploys IBM Cloud
Orchestrator.

VMBridge

br4096

The bridge name created in the

hypervisor, only for nova-network.

VMClusterName

The cluster name in vCenter that is

used for the virtual machine. This
parameter is only for a VMware
Region.

VMDataStoreName

The datastore cluster name in

vCenter that is used to put the
virtual machine.
You can specify a regular expression
to match the name of a datastore. For
example, VMDataStoreName="nas.*"
selects all the datastores that have a
name starting with "nas".

VMDns1

The primary DNS used by

nova-network.
Change it to your corporate DNS.
Must be specified as an IP address
but not as the host name, for
example: 10.178.144.228.

216

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 21. Deployment parameters (continued)

Name

Default Value

Description
The secondary DNS used by
nova-network.

VMDns2

Change it to your corporate DNS.

Must be specified as an IP address
but not as the host name, for
example: 10.178.144.228.
VMEndIP

10.10.0.200

The final IP address of the virtual

machine IP range that is used by IBM
Cloud Orchestrator. It is only used by
nova network.

VMGATEWAY

10.10.0.1

The gateway of the virtual machine

network.

VMNETLABEL

demo

The label of the virtual machine

network.

VMInterface

vmnic0

The VMware physical Ethernet

adapter name for vlan networking.
Change it to the actual adapter used
The nova network manager will
create vlan port groups attached to
this nic when required. This
parameter is only for a VMware
Region.

VMIPV4ADDR

10.10.0.0/24

The default subnet for nova-network.

Change it according to your
datacenter environment.

VMServerHost

The VMware vCenter host. This

parameter is only for a VMware
Region.

VMServerUserName

This attribute is used to specify the

ID of an authorized user which is
used (together with the password
parameter specified in
VMServerPassword) to connect to a
VMware Virtual Center server. If this
identity is an Active
Directory domain user where the
domain is a mandatory part of the
user id, then it must to be given in
the following format: userid@domain.

VMServerPassword

The password of the user specified in

VMServerUserName.
This parameter cannot contain any
special characters like for example:
$ ^ ( ) + . [ \ ? | %'.

VMStartIP

10.10.0.100

The initial IP address of the virtual

machine IP range that is used by IBM
Cloud Orchestrator. It is only used by
nova network.

VMVLANID

100

Vlan ID of the virtual machine

network.
Chapter 2. Installing

217

Table 21. Deployment parameters (continued)

Name

Default Value

Description
VMware wsdl location. This
parameter is only for a VMware
Region.

VMWsdlLocation

VXLANMcastGroup

224.0.0.100

VXLAN multicast group. It is used

only for Neutron networks.

VXLANVniRange

1000:1600000

VXLAN VNI range. It is used only

for Neutron networks.

WorkloadDeployerTmpPath

/tmp/iwd

The temporary path for Workload

Deployer to save binary.
The path can be created or accessed
by the user that deploys IBM Cloud
Orchestrator.

Quota-related installation parameters

You can alter the default quota values for OpenStack projects at installation time.

Quota related installation parameters

When deploying IBM Cloud Orchestrator to VMware environments with existing
workload, it is possible to exceed the default quotas based on discovered
workload. In that situation, or any other situation where the default quotas are
known to be insufficient at installation time, the following Region Server
parameters can be used:
Table 22. Deployment parameters for quota
Name

Default Value

Description

QuotaCores

20

Quota for cores

QuotaDriver

nova.quota.DbQuotaDriver

Quota for driver

QuotaFixedIps

-1

Quota for fixed IP addresses

QuotaFloatingIps

10

Quota for floating IP addresses

QuotaInjectedFileContentBytes

10240

Quota for injected file content bytes

QuotaInjectedFilePathBytes

255

Quota for injected file path bytes

QuotaInjectedFiles

Quota for injected files

QuotaInstances

10

Quota for instances

QuotaKeyPairs

100

Quota for key pairs

QuotaMetadataItems

128

Quota for metadata items

QuotaRam

51200

Quota for RAM

QuotaSecurityGroupRules

20

Quota for security group rules

QuotaSecurityGroups

50

Quota for security group

218

IBM Cloud Orchestrator 2.4.0.2: User's Guide

System files modified by the installation procedure

The following system files and folders are modified during the IBM Cloud
Orchestrator installation.
v On Deployment Server:
/etc/group
/etc/passwd
/etc/ntp.conf
/etc/fstab
/etc/httpd/conf/httpd.conf
/etc/httpd/conf.d/
/etc/rc.local
/etc/security/limits.conf
/etc/sysconfig/iptables
/etc/sysctl.conf
/proc/sys/net/ipv4/ip_forward

v On Central Server 1:
/etc/group
/etc/passwd
/etc/hosts
/etc/sysconfig/iptables
/etc/security/limits.conf
/etc/sysctl.conf

v On Central Server 2:
/etc/group
/etc/passwd
/etc/hosts
/etc/sysconfig/iptables
/etc/security/limits.conf
/etc/sysctl.conf

v On Central Server 3:
/etc/hosts
/etc/sysconfig/iptables
/etc/security/limits.conf
/etc/sysctl.conf
/etc/sudoers
/etc/ntp.conf

v On Region Server:
/etc/group
/etc/passwd
/etc/hosts
/etc/sysconfig/iptables
/etc/security/limits.conf
/etc/sysctl.conf

v On System Automation Application Manager server:

/etc/sudoers

Chapter 2. Installing

219

220

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 3. Administering
After you have installed IBM Cloud Orchestrator, you can start your environment,
configure optional settings, and define users, projects, and domains as described in
the following sections.

Starting or stopping IBM Cloud Orchestrator

You can start or stop IBM Cloud Orchestrator.

Before you begin

This process does not apply to High-Availability Distributed installations. For
details of how to start or stop IBM Cloud Orchestrator in high-availability
installations, see Controlling the management stack on page 243.
Before you run the SCOrchestrator.py script, review Managing services with
SCOrchestrator.py, and ensure that your environment satisfies the conditions for
running the script.

About this task

You can run the SCOrchestrator.py script to start, stop, and view the status of the
IBM Cloud Orchestrator components.
For information about running the SCOrchestrator.py script, see Running the
SCOrchestrator.py script on page 225.
If you are using System Automation Application Manager, IBM Cloud Orchestrator
must only be started and stopped via System Automation Application Manager
and must not be managed by the SCOrchestrator.py script. For more information,
see Controlling the management stack on page 243.
To completely stop the IBM Cloud Orchestrator system:
1. Run the SCOrchestrator.py script to stop all services. For information about
running the SCOrchestrator.py script, see Running the SCOrchestrator.py
script on page 225.
2. Stop your virtual machines in no specific order.
To start the IBM Cloud Orchestrator system when nodes are down:
1. Start all the virtual machines in no particular order .
2. Run the SCOrchestrator.py script to stop all services. Check that all services
have stopped.
3. Run the SCOrchestrator.py script to start all services.
4. Restart NoSQL by following the procedure described in Restarting NoSQL on
page 235.

Copyright IBM Corp. 2013, 2015

221

Accessing IBM Cloud Orchestrator user interfaces

IBM Cloud Orchestrator provides several user interfaces to access the various
components.
To correctly display the IBM Cloud Orchestrator user interfaces, use one of the
following browsers:
v Internet Explorer versions 10, and 11
v Firefox Extended Support Release 31
v Google Chrome version 37
Access to the various IBM Cloud Orchestrator user interfaces depends on the role
assigned, as shown in the following table:
User interface

URL

Access granted to

Administration user interface

https://central-server-ihs_fqdn

admin role only

Self-service user interface

https://central-serverihs_fqdn:8443

admin role
domain_admin role
catalogeditor role
member role

Business Process Manager user

interface

https://central-serverihs_fqdn:8443/ProcessCenter/
login.jsp

admin role only

Each IBM Cloud Orchestrator user interface URL includes the following
specification:
https://central-server-ihs_fqdn

where central-server-ihs_fqdn is the fully qualified DNS domain name of the

Central Server where the IBM HTTP Server is installed. In a multiple-region
deployment, the IBM HTTP Server is installed on Central Server 2.
In High-Availability Distributed installations, central-server-ihs_fqdn is the host
name of the virtual address used for Central Server 2, that is the value specified
for the CentralServer2VirtualHostname parameter at installation time. For more
information, see Installing the Central Servers on page 55.
Note:
v The fully qualified DNS domain name is in the form x.y.z, as shown in the
following example:
host.example.com

v Do not use the IP address to access the IBM Cloud Orchestrator user interfaces.
v When logging to the Administration user interface, if you save the password
details with the browser, these details might be loaded unexpectedly in the
Update User dialog for that user. To avoid this behaviour, you must clear the
password details from the browser.
v If you are using the Administration user interface in non-English language, you
might see English strings because of OpenStack limitations.
You can extend the Self-service user interface URL to include the IBM Cloud
Orchestrator domain name, as shown in the following example:
https://central-server-ihs_fqdn:8443/login?domainName=myDomain

222

IBM Cloud Orchestrator 2.4.0.2: User's Guide

In this example, the Domain field on the login screen is prepopulated with the
value myDomain. If you do not specify a domain, the user is authenticated to the
Default domain.
By default, the user is also authenticated to the scope of the primary project that
you specified when you created the user. After you log in, you can change the
project scope by selecting a new project from the project list in the top banner of
the user interface. For more information about users, projects, and domains, see
Managing security on page 252.
Note: In IBM Cloud Orchestrator, the following limitations apply:
v A user name cannot contain a colon (:) character.
v A password cannot contain an at sign (@) character.
v Users cannot log in if the primary project to which they are assigned is disabled.
v You cannot log in to the same IBM Cloud Orchestrator user interface with more
than one browser session on the same machine. If you must log in to the same
IBM Cloud Orchestrator user interface with two browser sessions on the same
machine, use a different browser for each session. For example, use an Internet
Explorer browser and a Firefox browser.
v The Administration user interface login credentials are case-sensitive.
To view the IBM Cloud Orchestrator user interface in another language, set the
language option in your browser. Move the preferred language to the top of the
list, clear the browser cache, and refresh your browser view. For some browser and
operating system combinations, you might need to change the regional settings of
your operating system to the locale and language of your choice.
You must set the locale in Business Process Manager separately. Log into the
Business Process Manager user interface, and click Preferences. Select the locale
from the Locale preferences list, and click Save changes. You might need to log in
again for the changes to take effect.

Managing the services

Understand how to manage the IBM Cloud Orchestrator services.

Managing services with SCOrchestrator.py

The SCOrchestrator.py Python script can start, stop, and provide information
about the status of IBM Cloud Orchestrator services.
The SCOrchestrator.py script is installed on Central Server 1, in the
/opt/ibm/orchestrator/scorchestrator directory. If you install IBM Cloud
Orchestrator as highly available, the SCOrchestrator.py script is not installed.
Instead, you use System Automation Application Manager to manage the IBM
Cloud Orchestrator services. For more information, see Controlling the
management stack on page 243.
IBM Cloud Orchestrator contains of a number of services and modules, which
have to be online or running before the product can be used. The modules and
services are spread across several virtual appliances. Because some of these
modules and services require being started and stopped in sequence, IBM Cloud
Orchestrator is delivered with the SCOrchestrator.py script to start, stop, and
monitor the status of a single component or to start and stop all the IBM Cloud
Orchestrator services with one command. If you use the SCOrchestrator.py script
Chapter 3. Administering

223

to start or stop all the IBM Cloud Orchestrator services, the services are started or
stopped in the correct sequence and all the dependencies are resolved.
The SCOrchestrator.py script uses XML files to obtain the information about the
environment and the components:
v SCOEnvironment.xml
v SCOComponents.xml
v SCOEnvironment_fulltopo.xml
The XML files define the names and the start or stop priority of the IBM Cloud
Orchestrator services.
The SCOEnvironment.xml file is automatically generated by the installation
procedure when the central IBM Cloud Orchestrator servers are installed.
Afterwards, the installation procedure automatically updates the file if a Region
Server is installed. You must manually modify the file only if a Region Server is
removed.
The following sequence occurs when you run SCOrchestrator.py:
1. The script invokes SCOEnvironment_update.py to refresh the region topology
and generate or update the SCOEnvironment_fulltopo.xml file.
2. The script reads the SCOEnvironment_fulltopo.xml file, or the
SCOEnvironment.xml file if the SCOEnvironment_fulltopo.xml file does not exist,
and the SCOComponents.xml file.
3. The script obtains the parameters and options and analyzes them for the
actions to take.
4. For start, stop, and status sequences, scripts are copied to the specific systems
and executed on the remote systems.
5. The scripts are cleaned up from the /tmp directory of the systems.
The script files which are executed on the systems are in the same directory as the
SCOrchestrator.py script.
You can start or stop certain components if you know the exact name of the
component or host name. You can start or stop all modules of a specific virtual
machine by using the host name of the machine. As a result, all components of
that machine are started or stopped.
Note: Because some IBM Cloud Orchestrator services must be started in a given
sequence to work correctly, do not start or stop any single services but only start or
stop the whole IBM Cloud Orchestrator stack. Only experienced administrators
who are aware of the dependencies between the IBM Cloud Orchestrator services
can use the SCOrchestrator.py script to start or stop single services.

Assumptions for running the SCOrchestrator.py script

v The script is executed as root on the Central Server 1.
v Components of additional compute nodes are hardcoded.
v No Windows operating system support on management systems.

224

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Running the SCOrchestrator.py script

You can run the SCOrchestrator.py script to start, stop and view the status of the
IBM Cloud Orchestrator components.

Procedure
1. As root, navigate to /opt/ibm/orchestrator/scorchestrator on the Central
Server 1.
2. Run the SCOrchestrator.py script with the following options:
v To start the whole product, run ./SCOrchestrator.py --start.
v To stop the whole product, run ./SCOrchestrator.py --stop.
v To view the status of components, run ./SCOrchestrator.py --status.
v To view help for this script, run ./SCOrchestrator.py --help. The following
help is displayed:
Usage: SCOrchestrator.py [options]
Options:
-h, --help
-s, --start

shows this help message and exit

starts IBM Cloud Orchestrator with default parameters in
default sequence
--halt, --shutdown, --stop
stops IBM Cloud Orchestrator in default sequence
--status
shows status of components of IBM Cloud Orchestrator
-c SCOComponents.xml, --componentfile=SCOComponents.xml
defines the input properties filename. Default name is
SCOComponents.xml
-e SCOEnvironment.xml, --environmentfile=SCOEnvironment.xml
defines the environment filename. Default name is
SCOEnvironment.xml
-n SYSTEMSLIST, --hostips=SYSTEMSLIST
list of host IPs to start/stop format
hostip1,hostip2,hostip3,...
-p COMPONENTSLIST, --components=COMPONENTSLIST
list of components to start/stop format
component1,component2,component3,...
--version
shows SCOrchestrator.py version and exits

To view a list of components that can be specified with the -p option, open the
SCOEnvironment_fulltopo.xml file that lists all available component names for
each host of the IBM Cloud Orchestrator environment.

Running the SCOrchestrator.py script with non-root user

The following commands are all run as root on the server indicated.

Procedure
1. Create a new user ssh for all the Central Servers and Region Servers:
a. On each of the Central Servers and Region Servers:
Create a new user <yourmechid> and set the password:
useradd -m <yourmechid>
passwd <yourmechid> #enter at the prompt <yourmechpwd>

Create an .ssh directory and set file permissions:

su - <yourmechid> -c "mkdir .ssh; chmod 700 .ssh"

b. On Central Server 1:
Generate the ssh keys for <yourmechid> and copy it to all IBM Cloud
Orchestrator servers:
su - <yourmechid> -c "ssh-keygen -q -t rsa -N -f ~/.ssh/id_rsa"

Chapter 3. Administering

225

Here $i stands for the IP address of each IBM Cloud Orchestrator server
including Central Server 1:.
[root@cs-1] su <yourmechid>
[yourmechid@cs-1] scp ~/.ssh/id_rsa.pub $i:~/.ssh/authorized_keys

Note: It is important in the command above that you accept the server key
and the password required is of <yourmechid>.
c. Verify that <yourmechid> on Central Server 1 can ssh to all the IBM Cloud
Orchestrator servers including central Server 1 without interruption:
su - <yourmechid> -c "ssh <yourmechid>@$SCO_server_ip"
su - <yourmechid> -c "ssh <yourmechid>@$SCO_server_ip"

2. Copy the /opt/ibm/orchestrator and change the directory permission:

On Central Server 1, copy the directory /opt/ibm/orchestrator to
/home/<yourmechid>:
cp -rf /opt/ibm/orchestrator/scorchestrator /home/<yourmechid>

Change the owner of /home/<yourmechid>:

chown -R <yourmechid>:<yourmechidgroup> /home/<yourmechid>/

3. On each of the IBM Cloud Orchestrator servers, add the user <yourmechid> in
the sudo list:
a. Create a sudoer file named <yourmechid> and place it in /etc/sudoers.d.
The content of the file <yourmechid> is like what follows:
Note: Replace <yourmechid> with your new user name.
# sudoers additional file for /etc/sudoers.d/
# IMPORTANT: This file must have no ~ or . in its name and file permissions
# must be set to 440!!!
# this file is for the SAAM mech-ID to call the SCO control scripts
Defaults:<yourmechid> !requiretty
# scripts found in control script directory
# adapt the directory names to the mech id!
Cmnd_Alias SACTRL = /tmp/*.sh
# allow for
<yourmechid> ALL = (root) NOPASSWD: SACTRL

b. Change the sudoer file permission:

chmod 440 <yourmechid>

4. On Central Server 1, run these commands from the command prompt:

sed -i "s/\.\//sudo \.\//g" /home/<yourmechid>/scorchestrator/SCOrchestrator.py
sed -i "s/\.\//sudo \.\//g" /home/<yourmechid>/scorchestrator/SCOEnvironment_update.py
sed -i -e s/^SSH_USER.*/SSH_USER = "<yourmechid>"/g \
/home/<yourmechid>/scorchestrator/SCOrchestrator.py
sed -i -e s/^SSH_USER.*/SSH_USER = "<yourmechid>"/g \
/home/<yourmechid>/scorchestrator/SCOEnvironment_update.py

5. Run SCOrchestrator.py:
Move to the path /home/<yourmechid>/scorchestrator and run
SCOrchestrator.py with user <yourmechid>:
[root@cs-1] cd /home/<yourmechid>/scorchestrator
[root@CS-1 scorchestrator]# su <yourmechid>
[yourmechid@CS-1 scorchestrator2]$ ./SCOrchestrator.py

For the usage of SCOrchestrator.py, refer to Running the SCOrchestrator.py

script on page 225.

226

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Managing IBM Cloud Orchestrator services manually

In a standard multiple region deployment environment, you can check and start
the services of IBM Cloud Orchestrator.
In general, to manage services you use SCOrchestrator.py; however, if you are an
advanced user you can manage services manually.
The following table illustrates how you can check and start the services of IBM
Cloud Orchestrator.
Note: If you are using an all-in-one topology, all the services run on the same
computer.
Table 23. Managing IBM Cloud Orchestrator services manually
Command to check the
service

Command to start the

service

DB2

ps -ef | egrep '^db2';

netstat -an | grep 50000 |
grep LISTEN

su - db2inst1; db2start

openstack-ceilometercollector

service
openstack-ceilometercollector status

service
openstack-ceilometercollector start

openstack-ceilometercentral

service
openstack-ceilometercentral status

service
openstack-ceilometercentral start

openstack-ceilometernotification

service
openstack-ceilometernotification status

service
openstack-ceilometernotification start

Business Process Manager

service bpm status

service bpm start

Self-service user interface

service scui status

service scui start

Public Cloud Gateway

service pcg status

service pcg start

Keystone

service openstack-keystone
status

service openstack-keystone
start

openstack-ceilometer-api

service
openstack-ceilometer-api
status

service
openstack-ceilometer-api
start

Administration user
interface

service httpd status

service httpd start

IBM HTTP server

service ihs status

service ihs start

Workload Deployer

service iwd status

service iwd start

Server name

Components deployed

Central Server 1

Central Server 2

Central Server 3

Chapter 3. Administering

227

Table 23. Managing IBM Cloud Orchestrator services manually (continued)

Command to check the
service

Command to start the

service

openstack-nova-api

service openstack-nova-api
status

service openstack-nova-api
start

openstack-nova-scheduler

service
openstack-nova-scheduler
status

service
openstack-nova-scheduler
start

openstack-nova-conductor

service
openstack-nova-conductor
status

service
openstack-nova-conductor
start

openstack-glance-api

service
openstack-glance-api status

service
openstack-glance-api start

openstack-glance-registry

service
openstack-glance-registry
status

service
openstack-glance-registry
start

openstack-cinder-api

service
openstack-cinder-api status

service
openstack-cinder-api start

openstack-cinder-volume

service
openstack-cinder-volume
status

service
openstack-cinder-volume
start

openstack-cinder-scheduler

service
openstack-cinder-scheduler
status

service
openstack-cinder-scheduler
start

openstack-heat-api

service openstack-heat-api
status

service openstack-heat-api
start

openstack-heat-api-cfn

service
openstack-heat-api-cfn
status

service
openstack-heat-api-cfn start

openstack-heat-apicloudwatch

service
openstack-heat-apicloudwatch status

service
openstack-heat-apicloudwatch start

openstack-heat-engine

service
openstack-heat-engine
status

service
openstack-heat-engine start

openstack-ceilometernotification

service
openstack-ceilometernotification status

service
openstack-ceilometernotification start

openstack-ceilometercollector

service
openstack-ceilometercollector status

service
openstack-ceilometercollector start

openstack-ceilometercentral

service
openstack-ceilometercentral status

service
openstack-ceilometercentral start

neutron-server

service neutron-server
status

service neutron-server start

Server name

Components deployed

Region Server

228

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 23. Managing IBM Cloud Orchestrator services manually (continued)

Command to check the
service

Command to start the

service

neutron-linuxbridge-agent

service
neutron-linuxbridge-agent
status

service
neutron-linuxbridge-agent
start

neutron-l3-agent

service neutron-l3-agent
status

service neutron-l3-agent
start

neutron-metadata-agent

service
neutron-metadata-agent
status

service
neutron-metadata-agent
start

neutron-dhcp-agent

service neutron-dhcp-agent
status

service neutron-dhcp-agent
start

openstack-nova-compute

service
openstack-nova-compute
status

service
openstack-nova-compute
start

openstack-nova-apimetadata

service
openstack-nova-apimetadata status

service
openstack-nova-apimetadata start

neutron-linuxbridge-agent

service
neutron-linuxbridge-agent
status

service
neutron-linuxbridge-agent
start

Server name

Components deployed

Neutron Network Node

KVM Compute Node

In a high availability topology, services on central server 2 and region servers are
configured highly available on respective secondary nodes. They are illustrated in
the following table:
Table 24. Servers and their high availability configuration
Command to check the
service

Command to start the

service

openstack-ceilometer-api

service
openstack-ceilometer-api
status

service
openstack-ceilometer-api
start

Keystone

service openstack-keystone
status

service openstack-keystone
start

Administration user
interface

service httpd status

service httpd start

IBM HTTP server

service ihs status

service ihs start

Business Process Manager

service bpm status

service bpm start

Self-service user interface

service scui status

service scui start

Public Cloud Gateway

service pcg status

service pcg start

Keystone

service openstack-keystone
status

service openstack-keystone
start

Administration user
interface

service httpd status

service httpd start

IBM HTTP server

service ihs status

service ihs start

Business Process Manager

service bpm status

service bpm start

Self-service user interface

service scui status

service scui start

Server name

Components deployed

Central Server 2 Primary

Central Server 2 Secondary

Chapter 3. Administering

229

Table 24. Servers and their high availability configuration (continued)

Command to check the
service

Command to start the

service

openstack-ceilometercentral

service
openstack-ceilometercentral status

service
openstack-ceilometercentral start

openstack-ceilometercollector

service
openstack-ceilometercollector status

service
openstack-ceilometercollector start

openstack-ceilometercompute

service
openstack-ceilometercompute status

service
openstack-ceilometercompute start

openstack-ceilometernotification

service
openstack-ceilometernotification status

service
openstack-ceilometernotification start

openstack-cinder-api

service
service
openstack-cinder-api status openstack-cinder-api start

openstack-cinder-scheduler

service
openstack-cinder-scheduler
status

service
openstack-cinder-scheduler
start

openstack-cinder-volume

service
openstack-cinder-volume
status

service
openstack-cinder-volume
start

openstack-glance-api

service
service
openstack-glance-api status openstack-glance-api start

openstack-glance-registry

service
openstack-glance-registry
status

service
openstack-glance-registry
start

openstack-heat-api

service openstack-heat-api
status

service openstack-heat-api
start

openstack-heat-api-cfn

service
openstack-heat-api-cfn
status

service
openstack-heat-api-cfn start

openstack-heat-apicloudwatch

service
openstack-heat-apicloudwatch status

service
openstack-heat-apicloudwatch start

openstack-heat-engine

service
openstack-heat-engine
status

service
openstack-heat-engine start

openstack-nova-api

service openstack-nova-api
status

service openstack-nova-api
start

openstack-nova-cert

service openstack-nova-cert service openstack-nova-cert

status
start

openstack-nova-conductor

service
openstack-nova-conductor
status

service
openstack-nova-conductor
start

openstack-novaconsoleauth

service
openstack-novaconsoleauth status

service
openstack-novaconsoleauth start

Server name

Components deployed

KVM Region Server

Primary

230

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 24. Servers and their high availability configuration (continued)

Command to check the
service

Command to start the

service

openstack-nova-metadataapi

service
openstack-nova-metadataapi status

service
openstack-nova-metadataapi start

openstack-novanovncproxy

service
openstack-novanovncproxy status

service
openstack-novanovncproxy start

openstack-nova-scheduler

service
openstack-nova-scheduler
status

service
openstack-nova-scheduler
start

neutron-server

service neutron-server
status

service neutron-server start

openstack-cinder-api

service
service
openstack-cinder-api status openstack-cinder-api start

openstack-cinder-scheduler

service
openstack-cinder-scheduler
status

service
openstack-cinder-scheduler
start

openstack-glance-registry

service
openstack-glance-registry
status

service
openstack-glance-registry
start

openstack-heat-api

service openstack-heat-api
status

service openstack-heat-api
start

openstack-nova-api

service openstack-nova-api
status

service openstack-nova-api
start

openstack-nova-cert

service openstack-nova-cert service openstack-nova-cert

status
start

openstack-nova-conductor

service
openstack-nova-conductor
status

service
openstack-nova-conductor
start

openstack-novaconsoleauth

service
openstack-novaconsoleauth status

service
openstack-novaconsoleauth start

openstack-nova-metadataapi

service
openstack-nova-metadataapi status

service
openstack-nova-metadataapi start

openstack-novanovncproxy

service
openstack-novanovncproxy status

service
openstack-novanovncproxy start

openstack-nova-scheduler

service
openstack-nova-scheduler
status

service
openstack-nova-scheduler
start

neutron-server

service neutron-server
status

service neutron-server start

Server name

Components deployed

KVM Region Server

Primary (continued)

KVM Region Server

Secondary

Chapter 3. Administering

231

Table 24. Servers and their high availability configuration (continued)

Command to check the
service

Command to start the

service

openstack-ceilometercentral

service
openstack-ceilometercentral status

service
openstack-ceilometercentral start

openstack-ceilometercollector

service
openstack-ceilometercollector status

service
openstack-ceilometercollector start

openstack-ceilometercompute

service
openstack-ceilometercompute status

service
openstack-ceilometercompute start

openstack-cinder-api

service
service
openstack-cinder-api status openstack-cinder-api start

openstack-cinder-scheduler

service
openstack-cinder-scheduler
status

service
openstack-cinder-scheduler
start

openstack-cinder-volume

service
openstack-cinder-volume
status

service
openstack-cinder-volume
start

openstack-glance-api

service
service
openstack-glance-api status openstack-glance-api start

openstack-glance-registry

service
openstack-glance-registry
status

service
openstack-glance-registry
start

openstack-heat-api

service openstack-heat-api
status

service openstack-heat-api
start

openstack-heat-api-cfn

service
openstack-heat-api-cfn
status

service
openstack-heat-api-cfn start

openstack-heat-apicloudwatch

service
openstack-heat-apicloudwatch status

service
openstack-heat-apicloudwatch start

openstack-heat-engine

service
openstack-heat-engine
status

service
openstack-heat-engine start

openstack-nova-api

service openstack-nova-api
status

service openstack-nova-api
start

openstack-nova-cert

service openstack-nova-cert service openstack-nova-cert

status
start

openstack-nova-compute

service
openstack-nova-compute
status

service
openstack-nova-compute
start

openstack-nova-conductor

service
openstack-nova-conductor
status

service
openstack-nova-conductor
start

openstack-novaconsoleauth

service
openstack-novaconsoleauth status

service
openstack-novaconsoleauth start

Server name

Components deployed

VMware Region Server

Primary

232

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 24. Servers and their high availability configuration (continued)

Command to check the
service

Command to start the

service

openstack-nova-metadataapi

service
openstack-nova-metadataapi status

service
openstack-nova-metadataapi start

openstack-novanovncproxy

service
openstack-novanovncproxy status

service
openstack-novanovncproxy start

openstack-nova-scheduler

service
openstack-nova-scheduler
status

service
openstack-nova-scheduler
start

neutron-linuxbridge-agent

service
neutron-linuxbridge-agent
status

service
neutron-linuxbridge-agent
start

neutron-server

service neutron-server
status

service neutron-server start

Server name

Components deployed

VMware Region Server

Primary (continued)

Chapter 3. Administering

233

Table 24. Servers and their high availability configuration (continued)

Command to check the
service

Command to start the

service

Server name

Components deployed

VMware Region Server

Secondary

openstack-cinder-api

service
service
openstack-cinder-api status openstack-cinder-api start

openstack-cinder-scheduler

service
openstack-cinder-scheduler
status

service
openstack-cinder-scheduler
start

openstack-glance-registry

service
openstack-glance-registry
status

service
openstack-glance-registry
start

openstack-heat-api

service openstack-heat-api
status

service openstack-heat-api
start

openstack-nova-api

service openstack-nova-api
status

service openstack-nova-api
start

openstack-nova-cert

service openstack-nova-cert service openstack-nova-cert

status
start

openstack-nova-compute

service
openstack-nova-compute
status

service
openstack-nova-compute
start

openstack-nova-conductor

service
openstack-nova-conductor
status

service
openstack-nova-conductor
start

openstack-novaconsoleauth

service
openstack-novaconsoleauth status

service
openstack-novaconsoleauth start

openstack-nova-metadataapi

service
openstack-nova-metadataapi status

service
openstack-nova-metadataapi start

openstack-novanovncproxy

service
openstack-novanovncproxy status

service
openstack-novanovncproxy start

openstack-nova-scheduler

service
openstack-nova-scheduler
status

service
openstack-nova-scheduler
start

neutron-linuxbridge-agent

service
neutron-linuxbridge-agent
status

service
neutron-linuxbridge-agent
start

neutron-server

service neutron-server
status

service neutron-server start

For information about the high availability policies of these services, see System
automation policies on page 240. If a service is configured active-active, it should
be running on both the primary and the secondary nodes. If a service is configured
active-passive, only one instance of the service should be running, on either the
primary or secondary node.
Some services do not apply to the current configuration, therefore must not be
running at all on either the primary or secondary node, for example
openstack-nova-console and openstack-nova-xvpvncproxy.

234

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Restarting NoSQL
To restart NoSQL, perform the following procedure.

Procedure
1. Log in as DB2 instance user (for example, db2inst1) by running the following
command:
su - db2inst1

2. Create the logs directory and prepare the wplistener.properties file by

running the following commands:
mkdir -p ~/json/logs
cat > ~/json/wplistener.properties
# Adjust below variables according your environment
# database name used by ceilometer
dbName=OPENSTACK
# mongo port used by ceilometer
mongoPort=27017
# Ceilometer database userid
userid=ceil
# Ceilometer database password
password=passw0rd
# Name of the Host running the noSQL process
noSQLHost=localhost
# Type Ctrl + D below to close the stream

3. Restart NoSQL by running the following commands:

export JAVA_HOME=~/sqllib/java/jdk64
cd ~/sqllib/json/bin
# stop noSQL
./wplistener.sh -logPath ~/json/logs -propsFile ~/json/wplistener.properties -shutdown
# start noSQL. Make sure the according database has been started
nohup ./wplistener.sh -logPath ~/json/logs -propsFile ~/json/wplistener.properties \
-start &> ~/json/logs/start.out &

Managing high availability

The High-Availability Distributed installation of IBM Cloud Orchestrator uses
System Automation Application Manager and System Automation for
Multiplatforms to achieve high availability.
Learn about System Automation Application Manager and System Automation for
Multiplatforms, how to configure these products for IBM Cloud Orchestrator, and
how to use them to start and stop the IBM Cloud Orchestrator management stack.
The following components provides high availability:
haproxy
Provides access to OpenStack services in high-availability configurations.
IBM HTTP Server
Balances the load for Business Process Manager in high-availability
configurations.
Qpid

Manages the messaging system used by the OpenStack services.

System Automation Application Manager

Automates the availability of resources by starting and stopping resources
Chapter 3. Administering

235

automatically and in the correct sequence. System Automation Application

Manager uses agentless adapters to monitor and control remote
applications. It provides a centralized server that monitors and
automatically stops, starts, or restarts the various applications on the
virtual machines in the IBM Cloud Orchestrator environment.
System Automation for Multiplatforms
Uses a clustering solution to provide high availability and automation for
critical IBM Cloud Orchestrator applications, such as haproxy.

High-availability solutions
Learn how to set up an IBM Cloud Orchestrator management stack with
high-availability quality of service (QoS), and reduce the downtime of the IBM
Cloud Orchestrator management stack.
IBM Cloud Orchestrator achieves high availability by using redundant active-active
installed components, where possible.
The high-availability capabilities of the IBM Cloud Orchestrator management stack
are supported by using the following products:
System Automation Application Manager
System Automation Application Manager automates the availability of
resources by starting and stopping resources automatically and in the
correct sequence. System Automation Application Manager uses agentless
adapters to monitor and control remote applications. System Automation
Application Manager ensures availability and provides automation of these
services across operating-system boundaries. System Automation
Application Manager provides a centralized server that monitors and
automatically stops, starts, or restarts the various applications on the
virtual machines in the IBM Cloud Orchestrator environment.
System Automation for Multiplatforms
System Automation for Multiplatforms is a clustering solution that
provides high-availability and automation features for critical components
such as applications, network interfaces, virtual IP addresses, and storage.
In the IBM Cloud Orchestrator environment, System Automation for
Multiplatforms can monitor and fail over critical components that rely on
an active-standby setup. System Automation for Multiplatforms uses
automation capabilities to ensure that actions are completed in the correct
order if a component fails. System Automation for Multiplatforms
automates services on Central Server 2, on KVM Region Servers, and on
VMware Region Servers.
These high-availability solutions are compatible and can be used together to
achieve high availability of the IBM Cloud Orchestrator management stack. When
you useSystem Automation Application Manager and System Automation for
Multiplatforms with IBM Cloud Orchestrator, you can recover the IBM Cloud
Orchestrator environment after hardware or software failure. This solution reduces
the downtime of the IBM Cloud Orchestrator management stack. In addition,
operation of the IBM Cloud Orchestrator management stack is simplified.
To use the hypervisor high-availability capabilities, you must complete extra
manual steps at installation time. For information about installing high availability,
see Deploying the High-Availability Distributed topology on page 53.

236

IBM Cloud Orchestrator 2.4.0.2: User's Guide

High-availability configurations
For the IBM Cloud Orchestrator management stack, high-availability quality of
service (QoS) can be provided in an active-active configuration or in an
active-standby configuration.
In a high-availability setup, the applications and services are usually configured as
redundant. One of the main differences between the high-availability
configurations is how the second server is set up.
active-active
In an active-active setup, the application is running on all instances. A load
balancer or proxy can be deployed to accept requests and to distribute the
requests to the nodes. Balancing the load in this way enhances
performance because more systems can handle the workload
simultaneously. To use the active-active setup, an application usually must
be designed to provide this capability: for example, to store and access the
underlying data.
active-standby
In an active-standby setup, the application is running on only one instance
at a time. It is often necessary to enforce this limit because the shared
storage or database might become corrupted if accessed by multiple
instances simultaneously. Applications that do not have an active-active
design are usually run in the active-standby mode when they are made
highly available.
System Automation for Multiplatforms provides services to both types of
high-availability configurations:
v For components in an active-standby setup, which is also known as warm
standby, System Automation for Multiplatforms provides monitoring and failover
capabilities, and ensures that exactly one instance of the service is running at
any time.
The application or service is installed and readily configured on both nodes. If
data access is necessary, the data can be made available to both nodes. If an
unrecoverable error occurs on the first node, the application and all related
services are stopped and automatically restarted on the second node.
v For components in an active-active setup, System Automation for Multiplatforms
provides monitoring and restart capabilities, and ensures that the service
remains online even if temporary outages occur.
The application or service is installed and readily configured in the active-active
setup on both nodes. If an unrecoverable error occurs on any node, System
Automation for Multiplatforms detects the problem and automatically recovers,
which ensures maximum performance.

Goal-driven automation
Goal-driven automation helps to maintain each component in the desired state,
when IBM Cloud Orchestrator is configured as highly available. Do not interfere
with goal-driven automation by doing manual actions.
Automation can be goal-driven or command-driven. In command-driven
automation, the command is issued without any preconditions. In goal-driven
automation, the desired state is computed from multiple persistent inputs.
When IBM Cloud Orchestrator is configured as highly available, the components
are managed by System Automation Application Manager and System Automation
for Multiplatforms. Both of these system automation products try to maintain a
Chapter 3. Administering

237

desired state for every resource that they manage. This desired state can be specified
as online or offline, and is calculated from the following input factors:
v The default state that is defined in the policy
v Operator requests sent from the System Automation Application Manager and
System Automation for Multiplatforms user interfaces
v Relationship to other resources, which might require a component to start or
stop
Therefore, it is important that you manage these resources by changing their
desired state. If you start or stop resources outside the scope of System
Automation Application Manager or System Automation for Multiplatforms, the
action is evaluated as an unwanted deviation from the automation goal, and can
result in countermeasures.
For more information about goal-driven automation and how to manage resources,
see the following web pages:
v Understanding automation goals and requests
v Working with resources
v System Automation Application Manager command-line interface
v Administering a resource group

Using System Automation Application Manager

Use System Automation Application Manager to automate the availability of
resources. System Automation Application Manager starts and stops resources
automatically and in the correct sequence.
System Automation Application Manager can detect if a software component of
IBM Cloud Orchestrator failed, and can then automatically restart it. As a result,
you can achieve an improved availability solution for the IBM Cloud Orchestrator
management stack. System Automation Application Manager continuously
monitors all the components and subcomponents of the IBM Cloud Orchestrator
management stack. In case of failure, it reacts by automatically restarting the failed
components and the related subcomponents. The System Automation Application
Manager configuration includes automation policies that define the start and stop
dependency graph for all the IBM Cloud Orchestrator components. As a result, the
operating team can start, stop, and monitor the state of the IBM Cloud
Orchestrator management stack. System Automation Application Manager also
simplifies the operating tasks because it is possible to control the IBM Cloud
Orchestrator management stack in a more granular manner on the component
level. For example, with a single request you can recycle one component such as
Business Process Manager.
During installation, the saamuser user is created on the system where System
Automation Application Manager is installed. The saamuser user is also created on
all systems that are accessed by the System Automation Application Manager
agentless adapter component. This user is authorized to control the services that
are managed by System Automation Application Manager. This authorization is
granted by a user-specific configuration in the /etc/sudoers.d/saam file.

238

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Using System Automation for Multiplatforms

Learn about System Automation for Multiplatforms resources, ServiceIPs, and
relationships.
The following concepts are used by System Automation for Multiplatforms:
Resources
To provide failover capabilities, resources in System Automation for
Multiplatforms are modelled as floater resources. A resource that can be
started on two nodes is visible as three resources: the overall resource
container (also called the aggregate resource), and a representation of the
resource on each node (also called constituent resources).
Modelling a resource in this way results in the following automation
behaviour:
v A floater resource ensures that only one constituent resource is started at
any time. If more than one active constituent is detected, the additional
constituents are stopped immediately.
v A floater resource has a desired state. If the resource is not in the desired
state, System Automation for Multiplatforms initates actions to achieve
the desired state. A resource that fails is restarted in place.
v If a resource experiences nonrecoverable errors, System Automation for
Multiplatforms attempts a failover: the constituent that is experiencing
the errors is marked as failed, and the other constituent is started.
v System Automation for Multiplatforms recognizes only status changes
made through its own interfaces as changes to the desired state. If
operations occur on a resource, System Automation for Multiplatforms
interprets those changes as unwanted changes and reestablishes the
desired state.
ServiceIPs
A typical problem in highly available services is reaching those services.
Independent access to the service must be established, regardless of which
constituent is currently online. To provide this access, System Automation
for Multiplatforms enables you to define a ServiceIP. A ServiceIP is a type
of floater resource and has the same properties as other floater resources.
Instead of managing an application, the ServiceIP provides an alias to a
network interface: for example, eth0:0 for eth0, with a new IP address.
ServiceIPs are also often called virtual IPs.
Relationships
A strong tie exists between an application and the IP address where the
application is available. If you automate an application and a ServiceIP,
you must ensure that both run on the same server, and that the ServiceIP is
available for the application at all times. To model such relations, System
Automation for Multiplatforms can define relationships of various types
between resources. The basic relationships are the start-stop dependencies
(for example, the ServiceIP must always be online before the HTTP Server
is started) and the location dependencies (for example, the ServiceIP and
the HTTP Server must always be on the same server).
The relationship used most commonly in the IBM Cloud Orchestrator
high-availability topology is the dependsOn relationship. The dependsOn
relationship combines multiple relationships and provides the following
automation behaviour for two resources where Resource A dependsOn
Resource B:

Chapter 3. Administering

239

1. Before Resource A is started, Resource B must be started. Resource A

waits for Resource B to be online before starting.
2. Before Resource B is stopped, Resource A must be stopped. Resource B
waits for Resource A to be offline before stopping.
3. Resource A must always be started on a server where Resource B is
already online.
4. If Resource B fails, Resource A is stopped. Then Rule #1 applies again.

System automation policies

When you install IBM Cloud Orchestrator in a high-availability topology, the
required automation policies are created automatically during installation.
Automation policies are XML files that contain a description of the automated
resources. The policy files include the following information:
v The systems that are run by the component
v The commands that are used to start, stop, and monitor the system
v The timeouts that should be enforced on these resources
v The relationships that should be considered when managing those resources
The following policies are used in IBM Cloud Orchestrator:
v One policy for every System Automation for Multiplatforms cluster
v One policy for every Agentless Adapter domain
v One end-to-end policy for the System Automation Application Manager domain
which integrates all other policies with one another
When you install IBM Cloud Orchestrator in a high-availability topology, the
following required automation policies are created automatically during the
installation:
v The System Automation for Multiplatforms policies are created and
automatically activated on the nodes of the System Automation for
Multiplatforms cluster.
v The System Automation Application Manager Agentless Adapter policies are
created on the node where System Automation Application Manager is installed,
and are activated from there. Exception: You must manually configure the
external IBM DB2 server as described in Configuring the external database
server for the high-availability topology on page 119.
v The end-to-end policy for the System Automation Application Manager must be
adjusted for every deployment of a Region Server. The installer automatically
extends the end-to-end policy file on the System Automation Application
Manager server, so that it can be activated manually.
v All of the above resources are combined in a System Automation Application
Manager end-to-end automation policy. This policy defines the Cloud
Orchestrator group. This group can be used to monitor the health of the IBM
Cloud Orchestrator system, and to start and stop IBM Cloud Orchestrator as a
single entity.

240

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Central Server 2 automation policy

When IBM Cloud Orchestrator is configured as highly available, a system
automation policy is created for Central Server 2.
In the high-availability topology, Central Server 2 is configured as a redundant
System Automation for Multiplatforms cluster consisting of two nodes. Some
components are configured as active-active, and some components are configured
as active-passive. System Automation for Multiplatforms also manages several
relationships between the components to ensure that the components are started
and stopped in the correct sequence. The following resources are managed in the
Central Server 2 cluster:
Table 25. . Resources managed by the Central Server 2 automation policy
Component

Resource name in policy

Type

IBM HTTP Server

ihs

Active-passive

haproxy

haproxy

Active-passive

IBM Business Process

Manager

bpm

Active-active

Keystone

keystone

Active-active

Horizon

horizon

Active-active

Public Cloud Gateway

pcg

Active-active

Self-service user interface

scui

Active-active

The Central Server 2 automation policy is configured as follows:

v Active-active resources run on both nodes. If a resource fails on one node,
System Automation for Multiplatforms restarts the resource on that node. If at
least one resource is still running, the service is monitored as online.
v Active-passive resources run on one node, preferably the first node. If the online
resource fails, System Automation for Multiplatforms restarts the resource on
that node, if possible. If a permanent error is detected, for example, the start
script returns an error code, a failover to the second node is initiated.
v IBM HTTP Server and haproxy depend on an IBM.ServiceIP resource that
represents a virtual IP address. If IBM HTTP Server or haproxy fails over, the
ServiceIP fails over first. All clients of these two services must connect to the
ServiceIP at all times. Otherwise, such clients cannot connect to the service (IBM
HTTP Server or haproxy) when it fails over.
Note: IBM HTTP Server and haproxy share the same ServiceIP. Therefore, both
services always run on the same node.

Region Server automation policy

When IBM Cloud Orchestrator is configured as highly available, a system
automation policy is created for each Region Server.
In the high-availability topology, each Region Server is configured as a redundant
System Automation for Multiplatforms cluster consisting of two nodes. Some
components are configured as active-active, and some components are configured
as active-passive. System Automation for Multiplatforms also manages several
relationships between the components to ensure that the components are started
and stopped in the correct sequence. The following resources are managed in the
Region Server clusters:

Chapter 3. Administering

241

Table 26. . Resources managed by the Region Server automation policy

Component

Resource name in policy

Type

haproxy

haproxy

Active-passive

qpid

qpid

Active-active

qpid-primary

Active-passive with hot

standby

ceilometer-central-agent

Single Instance

ceilometer-collector

Single Instance

ceilometer-compute-agents

Single Instance

cinder-api

Active-active

cinder-scheduler

Active-active

cinder-volume

Single Instance

glance-api

Single Instance

glance-registry

Active-active

heat-api-cfn

Single Instance

heat-api-cloudwatch

Single Instance

heat-api

Active-active

heat-engine

Single Instance

Neutron

neutron-api

Active-active

Nova

nova-api

Active-active

nova-cells

Active-active

nova-cert

Active-active

nova-compute-vmwarapi

Single Instance

nova-conductor

Active-active

nova-consoleauth

Active-active

nova-novncproxy

Active-active

nova-scheduler

Active-active

Ceilometer

Cinder

Glance

Heat

The Region Server automation policy is configured as follows:

v Single-instance resources run on the primary node only. If this resource fails,
System Automation for Multiplatforms restarts the resource on the primary
node. If the resource encounters a non-recoverable error, System Automation for
Multiplatforms indicates the error, but the resource remains in the failed state.
v Active-active resources run on both nodes. If a resource fails on one node,
System Automation for Multiplatforms restarts the resource on that node. If at
least one resource is still running, the service is monitored as online.
v Active-passive resources run on one node, preferably the primary node. If the
online resource fails, System Automation for Multiplatforms restarts the resource
on that node, if possible. If a permanent error is detected, for example, the start
script returns an error code, a failover to the second node is initiated.
v qpid is handled by two resources: qpid controls the qpid daemon, and
qpid-primary controls the assignment of the primary role and secondary role to
the resources. The qpid resource is active/active and the qpid-primary resource
is active-passive. The daemon resources are online on both nodes, but only the
primary node (Node A) accepts requests. The secondary resource acts as a
replication server, and provides a backup of the message queue: the message

242

IBM Cloud Orchestrator 2.4.0.2: User's Guide

broker copies all messages to the secondary node (Node B) before sending the
acknowledgment of receipt. When a failover occurs, the daemon resource is
restarted to ensure that the roles switch correctly: the original secondary node
(Node B) now becomes the primary node, and the qpid daemon runs on this
node. When the original primary node (Node A) comes back online, it starts as
the secondary node: the qpid-primary resource now runs on this node. After the
nodes reconnect to each other, the message queue is backed up on the new
secondary node (Node A).
v qpid-primary and haproxy depend on an IBM.ServiceIP resource that represents
a virtual IP address. If qpid-primary or haproxy fails over, the ServiceIP fails
over first. All clients of these two services must connect to the ServiceIP at all
times. Otherwise, such clients cannot connect to the service (qpid-primary or
haproxy) when it fails over.
Note: qpid-primary and haproxy share the same ServiceIP. Therefore, both
services always run on the same node. The qpid resource always runs on both
nodes and is independent of the IP address.

Controlling the management stack

Use System Automation Application Manager to control the IBM Cloud
Orchestrator management stack to shut down the whole stack or specific services
for maintenance and planned outages.

About this task

In addition to stopping a specific service, System Automation Application Manager
can also ensure that any dependencies between services are automatically resolved.
For example, if you want to stop DB2 for a backup, before stopping the DB2
service, all the services requiring DB2 are automatically stopped.
Important: If you plan to reboot or shut down an IBM Cloud Orchestrator virtual
machine, you must stop the IBM Cloud Orchestrator services on this virtual
machine via System Automation Application Manager before the OS is shut down
or rebooted. Otherwise,System Automation Application Manager might set a
resource in error. To resolve the error, follow the steps described in
Troubleshooting a high-availability installation on page 192. After the virtual
machine is started again, you can start the services by cancelling the offline request
as described in the following procedure.
To stop an IBM Cloud Orchestrator service by using System Automation
Application Manager, perform the following steps:

Procedure
1. Log on to System Automation Application Manager web user interface at
https://<SAAM server hostname>:16311/ibm/console/. Specify the user and
password that you defined during the installation. The default user is eezadmin.
2. Click the Operate end-to-end resources link. A view of the managed end to
end resources is displayed.
3. Click the plus sign in front of the top level resource SCOsaam to expand and
show the lower level resources.
4. In the Resources section for the policy, click the SCO resource group to expand
the list of all the related resources and resource groups.

Chapter 3. Administering

243

5. If you want to stop the whole IBM Cloud Orchestrator management stack,
select the top level resource SCOsaam and right-click the resource. Select
Request Offline. Enter a comment in the displayed window and click Submit.
6. If you want to stop a specific resource, right-click the resource name to select it
and click Request Offline.... Enter a comment in the displayed window and
click Submit. The service and all the dependent services are stopped. This only
works for resources that are managed by the agentless adapter.
7. To restart a resource or a resource group, right-click on the resource and select
Cancel Request.

Results
You stopped and restarted the IBM Cloud Orchestrator services.
For more information about using System Automation Application Manager, see
the System Automation Application Manager, Administrator's and User's Guide.

Managing settings
You can configure product settings before building a cloud infrastructure.

Before you begin

You must be assigned the admin role to manage the product settings.

Managing email delivery

The mail delivery function is used to send event notifications.

Before you begin

You must be assigned the admin role to perform these steps.

About this task

The mail delivery function is used to automatically notify the owner of a virtual
system instance about the following events:
v Virtual system instance is created.
v Virtual system instance has successfully started.
v Virtual system instance failed to start successfully.
v Virtual system instance is going to be removed due to expired reservation.
Note: For virtual system patterns, only the mail of deployment failure can be
received. The mail of deployment start and successful deployment cannot be
received.
To configure the mail delivery function, specify the required Simple Mail Transfer
Protocol (SMTP) server to be used for IBM Cloud Orchestrator by performing the
following steps:

Procedure
1. Click PATTERNS > Deployer Administration > Settings.
2. Expand Mail Delivery.

244

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. Add an SMTP server. Provide the IP address or host name for the SMTP server
to be used for IBM Cloud Orchestrator.
4. Add a reply-to address. The email address for the administrator should be used
for this field.

Results
The mail deliver function has been configured to send event notifications.

Configuring OpenStack synchronization

You can optionally change the default synchronization interval with the OpenStack
environment.

About this task

In IBM Cloud Orchestrator, the lists of cloud groups, hypervisors, and IP groups
are automatically imported from the OpenStack environment. This information is
periodically refreshed so that each change you make in the OpenStack
environment is automatically applied also in the IBM Cloud Orchestrator
environment.
To change the synchronization time interval, edit the /opt/ibm/rainmaker/
purescale.app/private/expanded/ibm/scp.ui-1.0.0/config/openstack.config file
(on the Central Server 3) and change the following statement:
/config/openstack = {
...
"synchronization": {
"initial_delay_sec": 60,
"interval_sec": 600,
"hypervisor_discovery_timeout_sec": 600,
"hypervisor_discovery_check_interval_sec": 10

where
initial_delay
Specifies the time interval (in seconds) between the start of the Workload
Deployer server and the first synchronization with the OpenStack
environment. It is optional. The default value is 60.
interval_sec
Specifies the time interval (in seconds) between the synchronizations with
the OpenStack environment. The default value is 600.
hypervisor_discovery_timeout_sec
Specifies the timeout after which the operation will be reported as failed.
hypervisor_discovery_check_interval_sec
Specifies the time interval for the hypervisor discovery operation. By
default, Workload Deployer will check every 10 seconds for a maximum of
10 minutes.

Chapter 3. Administering

245

Customizing the user interface

You can add views to the user interface in IBM Cloud Orchestrator as well as
change the branding for each domain.
The user interface is updated by editing the customization metadata properties in
the customizations.json file. A copy of this file is available in the following
directory after IBM Cloud Orchestrator is installed: {server_location}/etc/
customizations/template.
Note: {server location} is usually found in Central Server 2, path
/opt/ibm/ccs/scui/. The path is the same on all topologies.
This customizations.json file can be copied, updated, and added to a specific
domain directory under the main customization directory so the UI can be
customized. For example: {server_location}/etc/customizations/{domainName}.
Note: The template directory is present so that it can be duplicated and used as an
example when you are creating the customizations for other domains.
The customizations.json file that is located in{server_location}/etc/
customizations/default is used for customizations to the default domain. The
default domain is available by default after installation in the following directory:
{server_location}/etc/customizations.
The following topics explain the customizations.json file, the images folders and
how they can be edited to update the user interface that is based on the domain to
which you belong:

Branding the user interface per domain

You can change the domain branding and customize the user interface.
Metadata file properties in customization file:
The metadata file properties are contained in the customizations.json file. This file
contains both content and style metadata properties that are used to manipulate
the appearance of the IBM Cloud Orchestrator user interfaces for a particular
domain.
The following section explains the metadata file properties:
Content properties
The content properties section of the file contains all the label and static
type content that is customized. This content is generally text values and
links to replacement images, for example, if you want to use a different
logo. The following table shows the values that are contained in the
customizations.json file:
Table 27.

246

Content property values

Description

Text values

Items such as the title used in the main page

banner and the product title that is used on
the login page.

Image values

Items such as the product logo in the main

page banner and the product logo that is
used on the login page.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 27. (continued)

Content property values

Description

Content values

Items such as words, sentences, or resource

location paths. Content values substitute
dynamically replaceable elements in the
html template files in IBM Cloud
Orchestrator

Style properties
The style properties section of the file contains all the css style classes,
attributes, and elements that are customized. The style properties that are
defined must be legal css because it is this metadata that forms the direct
input for creating the css properties in the catalog-branding.css file. The
catalog-branding.css file is dynamically rendered through the Common
Custom Service. The catalog-branding.css is available at the following
URL:
<scuiHostName:port>/styles/catalog-branding.css

If you are logged in to a specific domain, the catalog-branding.css that is

used is the one that is specified by the domains customization. If no
catalog-branding.css is defined, the default css is used. When all of the
properties are defined, the IBM Cloud Orchestrator user interface uses the
Common Custom Service to change the look, feel, and style. The style
values include items such as the background color used in the main page
banner, the font, the logo, and so on.
The following example shows what the customizations.json metadata file looks
like:
{
"bannerLogo": "/customization/internal/images/IBM_logo.png",
"bannerLogoAlt": "IBM Cloud Orchestrator",
"title": "IBM Cloud Orchestrator",
"bannerBackgroundColor": "#003E68",
"bodyBackgroundColor": "#F4F6FB",
"bodyBackgroundImage": "",
"loginLogo": "/customization/images/black-ibm-logo.png",
"loginLogoAlt": "IBM Cloud Orchestrator",
"loginBackgroundColor": "#F4F6FB",
"loginBackgroundImage": ""
"logoutURL": "http://www.ibm.com"
}

IBM Cloud Orchestrator supports customizable properties that are defined in the
customizations.json file. These supported customizable properties are described
in the following table.
Table 28. Customizable properties
Metadata property values

Type

bannerLogo

File system path

bannerLogoAlt

Text

title

Text

bodyBackgroundColor

Text

bodyBackgroundImage

File system path

loginLogo

File system path

Chapter 3. Administering

247

Table 28. Customizable properties (continued)

Metadata property values

Type

loginLogoAlt

Text

loginBackgroundColor

Text

loginBackgroundImage

File System Path

logoutURL

Text

Note: bannerLogo can be max 20px high and 1000px wide.

Note: loginLogo can be max 30px high and 300px wide.
Note: Although you can enter an unlimited number of characters for the title
property, only titles with less than 50 characters are displayed on the User
Interface.
Note: For the bannerLogo and bodyBackgroundImage properties, the image name
specified must be preceded by /customization/internal/images/. For example,
if exampleLogo.png is the image file to use, then the property value
is /customization/internal/images/exampleLogo.png. For
the loginLogo and loginBackgroundImage properties, the image name specified
must be preceded by /customization/images/. For example,
if exampleLoginLogo.png is the image file to use, then the property value
is /customization/images/exampleLoginLogo.png. The files in the customizations/
{domainName}/images directory will be used for these properties.
All base customization files that are used in the IBM Cloud Orchestrator user
interface are found in the following location: {server_location}/etc/
customizations/template. For domains that are not customized, the default content
that is found in {server_location}/etc/customizations/default is used to alter
the style and provide the content to the user interface.
Note: This {server_location}/etc/customizations/template directory must not
be removed, as it is used as an example for all other customizations.
Customizing the user interface:
You can update the IBM Cloud Orchestrator user interface for a given domain.
Procedure
1. Create a directory under {server_location}/etc/customizations with the
name of the domain that you want to customize. The customization metadata is
stored in the customizations.json file in a specific domain directory under the
main custom directory. For example: {server_location}/etc/customizations/
{Domain1}
Note: {server location} is usually found in Central Server 2, path
/opt/ibm/ccs/scui/. The path is the same on all topologies.
Note: Branding changes are only visible to the domain they are declared for,
except the Default domain.
2. Create a file in the directory that you specified in step 1 and call it
customizations.json.

248

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: Copy the customizations.json file from the {server_location}/etc/

customizations/template directory to the new domain, for example, Domain1
and edit the file instead of manually creating the file.
3. Create a folder that is called images under the customizations/{domainName}
directory. For example: {server_location}/etc/customizations/{Domain1}/
images.
4. Copy the image file that is referenced in the content section of the
customizations.json file into the same customizations/{domainName}/images
directory. This method is used to ensure that all domain-specific customization
content is in the correct location
Note: You can also add and create new images and add them to the images
folder. However, you must update the customizations.json file accordingly,
based on any new image file that you add.
5. Restart the scui server and clear the custom cache for the changes to be picked
up. Restart the server as follows:
service scui restart

Enter the following link in your browser to clear the server cache:
http://<scuiHostName:port>/customization/clearcustomcache

6. Log in to the IBM Cloud Orchestrator user interface with the domain that was
customized and view the results to ensure that you are satisfied with the style
updates. To open the login screen for a specific domain, for example mydomain,
enter the following link in your browser:
http://<scuiHostName:port>/login?domainName=mydomain

Note: If an error is displayed in the user interface, it indicates that there is a

problem with the customization. Complete the following steps:
v View the server logs to find more information about the error:
/var/log/scoui.log and /var/log/scoui.trc.
v Ensure that the domain directory is correctly named, the
customizations.json file is in the correct format, and its contents are correct.

Dashboard extensions
A dashboard extension file is a single html file that displays one or more BPM
coaches. For the purpose of the dashboard extension these coaches should contain
dashboards, graphs or other reporting elements developed in BPM.
The user defined extension html file contains a fragment of html without a head or
a body element. These are included in the parent html file which embeds the
supplied extension content.
The html file must contain iframe tags to specify the Business Process Manager
dashboard coaches that you want to display on the page. In this case an iframe is
used to embed one html document, the dashboard coach, within another html
document, the parent extension. Define the width and height of the inline coach
frames to achieve the layout you want.
The following snippet of code is an example of a user defined html fragment with
a Business Process Manager dashboard iframe that is contained in a sample
extension html file:
<div align="center">
<iframe id="ifm" name="ifm" width="1000" height="1000" frameborder="0"
src="{{bpmEndpoint}}/teamworks/process.lsw?
Chapter 3. Administering

249

zWorkflowState=5&zProcessRef=/1.fc983f33-e98f-4999-b0b5bd1e39d6102e&zBaseContext=2064.abec322d-430c-43dd-820a98f223d29fa4T&applicationInstanceId=guid:6416d37cd5f92c3a:33127541:1461a68c1cd:7ffe&applicationId=2"
scrolling="auto" align="middle">
</iframe>
</div>

In the example there is the following mustache variable defined {{bpmEndpoint}}.

This utility variable is supplied by the extension framework. It enables extension
content providers to locate and specify the base Business Process Manager host
server url and port of an installed IBM Cloud Orchestrator instance in a generic
way. Having this variable available to extension deployers means that no manual
editing must be made to the html file after deployment to specify the location of
the Business Process Manager server. For more information related to mustache
see: http://mustache.github.io/mustache.5.html
Single sign-on is enabled between the Self Service UI and Business Process
Manager, so displaying Business Process Manager coaches in the UI does not
require any additional authentication configuration.
Role based directory structure:
Dashboards are role based. This allows service designers to have their dashboard
extension content available to specific roles.
The directory structure that the extension content is deployed into is based on the
IBM Cloud Orchestrator roles in the following table. The four IBM Cloud
Orchestrator roles which the extension is compatible with are:
Table 29.
Name of role directory

Role

member

End User

admin

Cloud Administrator

domain_admin

Domain Administrator

catalogeditor

Service Designer

The dashboard folder is the parent extension directory. It contains a folder for each
of the four roles. It is located on the Self-service user interface server at the
following location: {server_location}/etc/dashboard
e.g. {server_location}/etc/dashboard/admin or {server_location}/etc/
dashboard/member
When a service designer wants to make a new dashboard available to an admin
user, for example, they add the extension html file to the: {server_location}/etc/
dashboard/admin directory

250

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Navigation elements and extension naming conventions:

Naming extension files is important as these names drive the names of the
navigation elements where the dashboards are accessed from.
Navigation elements should be meaningful so that you can easily locate important
content in the UI. As these dashboard extension navigation elements are driven
from the names of the dashboard extension files, these file names should be
meaningful. Dashboard extensions appear as submenu items under the
DASHBOARD menu and take the name of the extension file as their menu label.
The label is the complete file name with any ordinal position specified and the file
extension removed.
The following table describes an example of file names and their respective menu
labels:
Table 30.
File

Menu label

01 - Admin Extension Example.html

Admin Extension Example

02 - Member Extension Example.html

Member Extension Example

Network Dashboard.html

Network Dashboard

Performance Dashboard.html

Performance Dashboard

Ordinal numbering of extension files is included so that you can control the order
in which the extension labels appear in the DASHBOARD menu. The ordinal
numbering format convention is a number, then a hyphen (-), then the file name.
Any file name starting with this pattern is placed in this relative numbered
position in the sub menu. The pattern is stripped from the file name when
constructing the label. If an ordinal numbering format convention is not used
when naming extension files the files is added alphabetically.
Packaging and deployment:
A dashboard extension made available via the market place must be packaged as a
compressed zip or tar.gz file.
The package structure must match the role based directory structure mentioned in
the previous section. For example:
extensionExample.zip
+ dashboard
+ admin
+ 01 - My Admin Extension Example.html

To deploy the extension, extract the compressed file to {server_location}/etc. To

have the new extension content appear in the UI, restart the icoui server.
Alternatively, enter the following link in your browser to clear the navigation
cache: <scuiHostName:port>/dashboardextension/clearcache
Note: Before deploying a dashboard extension ensure that there are no extension
files that have already been deployed previously in the extension directories with
the same name. Any deployed file with the same name as one file contained in the
package will get overwritten otherwise.

Chapter 3. Administering

251

Managing security
You can manage users and the level of access that each user has in the IBM Cloud
Orchestrator environment. You can assign which roles a user has on a specific
project, as well as the primary project for a user. A user can have different roles on
different projects. Both users and projects belong to a domain.

About this task

The OpenStack Compute system is designed to be used by many different
cloud-computing consumers or customers, basically projects on a shared system,
using role-based access assignments. Roles control the actions that a user is
allowed to perform. For example, you can define that a user cannot allocate a
public IP without the admin role. A user's access to particular images is limited by
project, but the username and password are assigned per user. Key pairs granting
access to an instance are enabled per user, but quotas to control resource
consumption across available hardware resources are per project.
A project is an isolated resource container forming the principal organizational
structure within the OpenStack environment. It consists of a separate VLAN,
volumes, instances, images, keys, and users. For more information about
OpenStack users and projects, see the OpenStack documentation.
For projects, quota controls are available to limit the following resources:
v Number of volumes that can be created
v Total size of all volumes within a project as measured in GB
v Number of instances that can be launched
v Number of processor cores that can be allocated
v Publicly accessible IP addresses
For more information about the OpenStack commands to be used to manage quota
values in the projects, see Configuring project quotas on page 268.
When you create users and projects in IBM Cloud Orchestrator, they are actually
being created in the underlying OpenStack environment. The roles that are defined
in the OpenStack environment are used in IBM Cloud Orchestrator as described in
User roles in IBM Cloud Orchestrator on page 255.
In IBM Cloud Orchestrator, the OpenStack concept of domain is also supported. A
domain represents a customer (that is, for example an organization or a division)
and the related resources as a segregated entity. Only users within that domain
have access to these resources. In this way service providers can use the same IBM
Cloud Orchestrator infrastructure to serve multiple customers. A domain can also
be seen as a sort of container for projects and users. A user or a project can belong
only to one domain. Domain administrators are authorized to create, update and
delete resources related to the domain.
Important: IBM Cloud Orchestrator does not support the definition of same
resource names in multiple domains at the same time (for example, a project with
same name exists in different domains). The cloud administrator must ensure that
there are no duplicated user names, project names, and domains.
When a user logs in to the IBM Cloud Orchestrator user interface, the user must
specify the domain scope to which the user wants to be authenticated. In a single
domain environment or if the user does not specify a domain, the users is

252

IBM Cloud Orchestrator 2.4.0.2: User's Guide

authenticated to the Default domain. In addition to the domain-based

authentication, when logging in, by default, the user is authenticated to scope of
the primary project that was specified when the user was created. After successful
authentication, the user can switch the project from the project list in the top
banner of the user interface.
Important: A user always authenticates on behalf of its domain. Therefore, as a
user, you must enter the domain name at the login page of IBM Cloud
Orchestrator. To login to Business Process Manager, you must specify the domain
name as a prefix of the username wherein the delimiter between domain name and
username is a '/'. For example, a user 'user1' of domain 'domain1' must specify
'domain1/user'. If you are a user who is within the default domain, you must
authenticate only with your username. Users and projects are shown in Business
Process Manager as users and groups. Any user or project of custom domains are
prefixed with the domain name delimited by '/', that is, project 'p1' of domain
'domain1' appears as a group 'domain1/p1' in Business Process Manager. To ensure
backward compatibility, users and projects of the default domain appear with its
user and project name. As the user and the project name are prefixed by their
domain name in Business Process Manager with a '/' as delimiter, the user name,
project name, and domain name must not contain a '/' character.
Note: In the current release of IBM Cloud Orchestrator user, project and domain
names are not case sensitive (for example, if a user is created with the name
George Windsor, you are able to login successfully also as george windsor).
If you are using an LDAP server to authenticate users, you can configure LDAP
authentication to allow any corporate directory details to be specified on a
domain-by-domain basis. For more information, see Configuring LDAP
authentication on page 72.
You can work with your users, projects (only to manage users), and domains with
the IBM Cloud Orchestrator user interface.

Model and terminology

The multitenancy model is based on the OpenStack identity service version 3. This
is implemented by Keystone. This includes the following entities and relationships.
Corporate
LDAP

Domain
1

Quota
1

n
Project

n
n

Membership

User

Quota

Role

n
[region, AZ]

n
Network

n
Image

n
Instances
(VMs, Stacks)

Domain
A domain is the highest entity in the identity model and represents a tenant as it is
a container and namespace for projects and users of a customer. IBM Cloud
Chapter 3. Administering

253

Orchestrator allows segregation on both the domain level and the project level.
Whether the domain concept is leveraged depends if the tenant should be allowed
to organize itself and requires the role of a domain administrator. If the domain is
a self-organized unit, create a domain and its domain administrator. A domain can
have multiple projects and users. The project and users are owned by a domain.
The domain administrator can manage the project and users and assign resources
to them. If the customer is not a self-organized unit and the administrator of the
service provider configures all projects, users and resources, the domain concept
can be ignored and the Default domain can be used. The Default domain always
exists.
User
A user represents the account of a person. You can log in to IBM Cloud
Orchestrator with a user account. A user account contains:
v user name
v password
v email address
A user is unique within a domain. You can have two different users with the same
name in two different domains. A user must always be member of at least one
project and have a default project defined.
Project
A project is a container which owns resources. Resources can be:
v virtual machines
v stacks
v images
v networks
v volumes
The project is unique within a domain. This means you can have two projects with
the same name in two different domains. A project can also have one or more
users as members. With a membership you can access all resources owned by the
project, so if you are a member of a project, you can access all resources owned by
that project.
Role
A role grants you access to a set of management actions. IBM Cloud Orchestrator
supports four different roles:
v admin
v domain_admin
v catalogeditor
v member
For information about the roles, see User roles in IBM Cloud Orchestrator on
page 255.
Scope

254

IBM Cloud Orchestrator 2.4.0.2: User's Guide

You can be member of one or multiple projects. As a user, you always work in the
scope of a project. When you log in, you work on-behalf-of a default project. If you
are a member of multiple projects, you can switch across projects in the self-service
banner.
LDAP
IBM Cloud Orchestrator can be configured to authenticate users with an LDAP or
Active Directory. It is allowed to configure one LDAP for all domains or a specific
LDAP per domain. If you log in to a domain with a LDAP configured you are
authenticated against the LDAP of that domain.

User roles in IBM Cloud Orchestrator

Protect your cloud environment by using roles to control how different users
interact with IBM Cloud Orchestrator. When you assign roles to users, you
designate the types of objects that the users can access, and the tasks that the users
can perform.
In IBM Cloud Orchestrator, the users and the projects are defined in the related
OpenStack environment. When you create a user, you must assign a role to the
user. The role is related to the project to which the user belongs. A user can have
one or many roles within a project, and can have different roles in different
projects.
The authority to access a type of object might not equate with the authority to
access all instances of that object. In some cases, users can access an object instance
only if they have been granted authority by the creator of that instance. See
Object-level access control on page 256 for more information.
In IBM Cloud Orchestrator, you can use the following roles:
admin role
A user with this role can do the following tasks in the IBM Cloud
Orchestrator environment:
v Create domains, projects, users, and roles.
v Assign other user roles. Configure product settings.
v Modify resources such as images, patterns, shared services, environment
profiles, other catalog content, and deployed cloud content.
v Grant users access to projects. Grant projects access to regions and
availability zones. Assign quotas to domains.
v Create environment profiles to group related cloud topology settings for
easy deployment of virtual system patterns. Environment profile creators
can also edit or delete any profile that they create, or to which they have
access.
v Download audit data. Change auditing settings that are editable, such as
the option to delete audit data from IBM Cloud Orchestrator after
download.
v Do all of the tasks that a user with the domain_admin role can do.
Important: A user with the admin role has full privileges for all cloud
resources, including all projects and all domains. Assign this role only to
the cloud administrators, and only to users within the Default domain and
admin project.

Chapter 3. Administering

255

domain_admin role
A user with this role can do the following tasks in the IBM Cloud
Orchestrator environment:
v View the details of the domain.
v View the projects, users, groups, offerings, and actions of the domain.
v Create, edit, and delete projects, users, groups, offerings, and actions that
are associated with the domain.
v Manage the quota, availability zones, and networks for projects in the
domain.
v Do all of the tasks that a user with the catalogeditor role can do.
catalogeditor role
A user with this role can do the following tasks in the IBM Cloud
Orchestrator environment:
v Create virtual system patterns and virtual application patterns. Edit or
delete any patterns that they create or to which they have access.
v Add objects to the IBM Cloud Orchestrator catalog. Modify or delete any
catalog content that they create or to which they have access.
v Import image files.
v Create self-service offerings, self-service categories, and orchestration
actions. Modify or delete any self-service offerings, self-service
categories, and orchestration actions that they create or to which they
have access.
v Do all of the tasks that a user with the member role can do.
member role
A user with this role can do the following tasks in the IBM Cloud
Orchestrator environment:
v View and manage the virtual system instances, patterns, and catalog
content to which they are granted access.
v Deploy virtual system patterns and virtual application patterns.
Important: A user with the member role cannot add, remove, or modify
any items.
Note: The following roles, which are showed in the Administration user interface,
are used only for the OpenStack services and not for IBM Cloud Orchestrator:
_member_
KeystoneAdmin
KeystoneServiceAdmin
sysadmin
netadmin

Object-level access control

IBM Cloud Orchestrator implements an object-level access control framework for
some object types. Users must have specific levels of access permissions to view, or
perform tasks with, instances of those objects. For example, a user with Member
role can only deploy a particular pattern if the user belongs to a project that has
been granted access to that pattern. Even a user with the catalogeditor role cannot
modify a particular pattern unless he or she created that pattern, or belongs to a
project that has been granted access to that pattern by the creator. Object-level
access applies to the following types of objects:
v Environment profiles

256

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v
v
v
v
v

Virtual images
Patterns
Script packages
Add-ons
Virtual system instances

v Shared services instances

v Orchestration actions
The following table depicts the object-level access definitions in IBM Cloud
Orchestrator. The all or owner definition applies to both the creator of the object
instance and the users with admin role (which has complete access to every
instance of every object that is created in the product). Object creators and users
with admin role can assign the object permissions read, write or all to other
projects.
Table 31. Object level access definitions
Access level definition

Description

Read

You can see the object listed in the user

interface panels and are able to view the
details for this object

Write

You can see the object listed in the user

interface panels and are able to view and
modify the details for this object.

All or owner

You can see the object listed in the user

interface panels and are able to view and
modify the details for this object. You are
able to delete this object.

None

If you are not assigned access to the object,

you cannot see the object listed in the user
interface panels. You cannot perform any
action associated with the object.

Related tasks:
Modifying the access control list of an action on page 329
You can modify the access control list of an action by adding or removing access.
Modifying the access control list of an offering on page 326
You can modify the access control list of an offering by adding or removing access.

Regions, availability zones and quota

This section describes regions, availability zones, and quota and their relationship
in IBM Cloud Orchestrator.

Chapter 3. Administering

257

IBM Orchestrator Services

Domain Default
Project 1

Domain Customer A

Project 2

Project A1

Domain Customer B

Project A2

Project A2

Keystone

Corporate
LDAP

OpenStack Region 1

OpenStack Region 2

OpenStack Region 3

OpenStack Region 4

KVM

EC2

VMware

Power

AZ 2.1

AZ 1.1

AZ 3.1

AZ 3.2

AZ 4.1

AZ 4.2

Compute Nodes
vCenter

AZ 1.2
Compute Nodes

ESX
Cluster 1

PowerVC

ESX

System p

System p

Cluster 2

Server Pool 1

Server Pool 2

A region is defined by a set of OpenStack services operating on the same

hypervisor. A region can manage a set of KVM hosts or a VMware vCenter
environment. It is not possible to manage different types of hypervisors within the
same region.
An availability zone is a subset of compute resources within a region. A region can
have many availability zones, but an availability zone can belong to only one
region. Availability zones are used as the target for deployment and as a user, you
must select the availability zone to place a virtual machine or stack.
IBM Cloud Orchestrator allows access of availability zones to Domains and
Projects to allow an End User to manage them.
It is possible to define a quota to limit the allocation of resources in the cloud. The
following definitions describe the different types of quota:
Domain Quota
The sum of all project quota must not exceed the domain quota. The
domain quota is only enforced if the Domain Administrator creates a new
project or modifies the quota of an existing project. If the domain quota is
exceeded, the Domain Administrator is not allowed to create the project or
increase the quota. The quota is not enforced for a Cloud Administrator.
Project Quota
The project quota is defined per region. In other words, the project can
have different quota in different regions. Both a Cloud Administrator and a
Domain Administrator can change the quota of a project in a region. The
quota the Domain Administrator cannot exceed the overall domain quota
while it is changing.
Default Quotas
Default quotas can be configured which are set for each new project. The
domain default quota is a multiplication of a factor of the default project
quota. Both default settings apply across domain and can only be
configured by the cloud administrator.

258

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Environment Profile Quota

The environment profile is used in Workload Deployer to grant a project to
an availability zone. An environment profile can have a quota. It is marked
obsolete because it is the same as a project quota. So, it is suggested to
manage the project quota rather than the environment profile quota.
If a user requests a service that allocates resources in the cloud, only the quota its
current project is checked and enforced. If the request exceeds the quota in that
region, the request fails with an error message. It is ensured by definition, that the
domain quota is not exceeded, as the Domain Administrator cannot give more
quota to its projects. Therefore, only check the project quota during deployment.

Network isolation
The segregation of tenants also requires the isolation of tenant networks.

Managed By Tenants

Managed by Service Provider

External
Network-1

Domain A

External
Network-2

Network-A1

Network-A2

Domain B

Network-A3

Network-B1

Tenant's web-tier
VM communicates
to external world
IP:
10.10.10.x

Domain A
Router

Internet
Tenant's web-tier
VM to DB-tier via
internal network

IP:
10.10.12.x
10.10.10.x
Floating IP:
192.0.10.x

Domain B
Router
192.0.10.1-10

192.0.11.1-10

10.10.12.0/24

10.10.10.0/24

Domain Admin

Cloud Admin
Provides physical Infrastructure and VLANs
Creates external networks and Routers
Hands over VLANs and external networks to Domain Admin

10.10.11.0/24 10.10.10.0/24

Creates networks for projects in the domain

Defines the subnet of the networks
Optionally, defines network routers between networks

IBM Cloud Orchestrator supports the following technologies to manage the

networks within the cloud:
v OpenStack Nova network service
v OpenStack Neutron network service
Details of the services can be found in Chapter 2, Installing, on page 15 or in the
OpenStack official documentation.
From a multi-tenancy perspective, the Neutron service provides the best
capabilities, which allow tenants to manage their network topology in separate
namespaces. This includes, overlapping IP scenarios, where two tenants can have
two separate networks each having the same overlapping IP subrange. The
isolation and separation is handled the Neutron service.

Chapter 3. Administering

259

The Cloud Administrator is responsible to manage the network topology. It is the

service provider and Cloud Administrator responsibility to provide the external
connectivity to the tenants.
In IBM Cloud Orchestrator, network isolation happens on the project layer, not on
the domain layer. A network is typically owned by a project, and a project can
have multiple networks.
The Domain Administrator can create private networks for projects within its
domain.
The End User, who requests virtual machines on behalf of the current project can
add one or more network interfaces. This ensures connectivity to one or more
networks of the project.
This means that a tenant can manage their internal connectivity and can define a
multi-tier application environment with different networks for database and
application traffic.
However, the external connectivity must be ensured by the Cloud Administrator.
For more information about managing networks, see Managing Nova networks
on page 88 and Managing Neutron networks on page 93.

Setting up PowerVC RSA keys

To inject a desired SSH key into a pLinux virtual machine at deploy time the
following steps must be done to ensure that the keys are available for use by both
PowerVC and IBM Cloud Orchestrator.

Procedure
1. Generate the Public and Private Key on the PowerVC server (this requires the
powervc-source file that is documented on page Making PowerVC images
compatible with Workload Deployer on page 346 in steps 8a and 8b):
ssh-keygen -t rsa -f test1.key

This will create a test1.key and a test1.key.pub which are the private and
public keys respectively.
2. Add a new key pair to the PowerVC key pair list ensuring that you select the
public key that was created in step 1:
nova keypair-add --pub-key test1.key.pub test1

3. Ensure the key pair is available on the PowerVC server:

nova keypair-list
+-------+-------------------------------------------------+
| Name | Fingerprint
|
+-------+-------------------------------------------------+
| test1 | 63:fd:a8:7e:50:31:b6:f9:ec:14:5d:e9:a6:ae:e1:e9 |
+-------+-------------------------------------------------+

4. Through Horizon or any other method you are familiar with, create a key pair
on IBM Cloud Orchestrator and specify the same name as the key pair on
PowerVC and ensure that you also specify the contents of test1.key.pub as the
public key.

260

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Results
You are now able to deploy a pLinux virtual machine from IBM Cloud
Orchestrator that can use the private key test1.key for access.

Administering as cloud administrator

Administer as a cloud administrator.
A common scenario for a Cloud Administrator is the onboarding of a customer or
organization, which must have the required administrator roles and cloud
resources assigned to be up and running. For details, see Managing a domain.
Note: The administration user interface does not support filtering with some
special characters for example: $ ^ ( ) + . [ \ ? | %

Managing a domain
You can manage domains in IBM Cloud Orchestrator with the Administration user
interface.

About this task

Domains represent a customer or an organization in a multi-tenant environment.
Perform the following steps for onboarding a customer in this environment. You
must be assigned the admin role to perform this procedure.

Procedure
1. Create a domain resource. This step automatically creates a default project for
the domain to facilitate user onboarding.
2. Ensure that the domain has access to at least one deployment availability zone.
This allows users in that domain to access virtual images and deploy virtual
servers when logged into the domain projects. The availability zones assigned
to the domain will then be visible to be assigned to projects within the domain.
3. To delegate the domain administration, ensure that at least one user is assigned
to the domain with domain_admin role. With this role, the Cloud
Administrator can delegate the administrative tasks of the domain to the
Domain Administrator who can then start creating projects and assigning users.
Note: The default OpenStack Cloud Administration domain Default should
not be disabled. If it is, you are unable to log in to the Orchestrator and
Administration UI as default Cloud Administrator. It makes the default Cloud
Administrator domain and projects not valid. If you disabled the domain, you
can enable it again in one of the following ways:
v Send an HTTP request as follows:
curl -i -X PATCH http://<HOST>:35357/v3/domains/default
-H "User-Agent: python-keystoneclient"
-H "Content-Type: application/json" -H "X-Auth-Token:<TOKEN>"
-d {"domain": {"enabled": true, "id": "default", "name": "Default"}}

v Update the domain to be enabled with the python client using V3 keystone.

Chapter 3. Administering

261

Creating a domain:
The Cloud Administrator creates domains to organize projects, groups, and users.
Domain administrators can update and delete resources in a domain.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the left navigation pane, click ADMIN > Identity Panel > Domains. The
Domains page opens.
3. Select Create Domain. The Create Domain window is displayed.
4. Specify the domain name and, optionally, the domain description.
5. Optional: Clear the Enabled check box to disable the domain. If the domain is
disabled, the Domain Administrator cannot create, update, or delete resources
related to the domain. New domains are enabled by default.
6. Click Create Domain.
Results
A message is displayed, indicating that the domain is created successfully. A
project called Default is automatically created for the new domain.
Assigning a zone to a domain:
Assigning a zone to a domain enables users within a zone to access a specific
domain.
Before you begin
You must be logged in with the admin role to complete these steps.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the domains page by clicking ADMIN > Identity Panel > Domains in
the navigation pane.
3. In the domains page, find the entry for the domain and click More > Edit in
the Actions column to open the Edit Domain window.
4. Click the Availability Zones tab. The Available Zones and the Assigned Zones
are listed in the following format: Zone_Name - Region_Name
5. To assign a zone to a domain, from the list of Available Zones, click the plus
button beside the zone name. The selected zone moves to the Assigned Zones
list. To return an Assigned Zone to an Available Zone, select the minus button
beside the zone name. Use the Filter field to search for specific zones.
6. When you have assigned all zones, click Save.
Results
A message indicates that the domain is modified successfully.

262

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Setting the default domain quotas:

The Cloud Administrator sets the default domain quota for certain resources to
specify the maximum amount of the resource that is available to the domain. The
Domain Administrator can then distribute that quantity among all the projects in
the domain.
Before you begin
You must be assigned the admin role to complete these steps.
About this task
The Cloud Administrator can assign a default project quota to certain resources, as
described in Configuring project quotas on page 268.
To generate the default domain quota values, IBM Cloud Orchestrator multiplies the
corresponding default project quota value by the projects_per_domain variable.
Note: The projects_per_domain variable is a multiplier that IBM Cloud
Orchestrator applies to the default project quotas, to calculate the default domain
quotas. The projects_per_domain variable does not specify the maximum number
of projects that can be created in a domain.
The default value of the projects_per_domain variable is 5. The Cloud
Administrator can change the value of the projects_per_domain variable, which
consequently changes the default domain quotas, as follows:
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Log in to Central Server 2 as a root user.
3. Add the following lines to the /etc/openstack-dashboard/local_settings file:
SCO_CONFIG = {
projects_per_domain: <number of projects>,
}

4. Restart the HTTPD service:

service httpd restart

Editing the domain quotas:

The Cloud Administrator can change the quotas of a domain to set limits on the
operational resources that a Domain Administrator can distribute among all the
projects in the domain.
Before you begin
You must be assigned the admin role to complete these steps.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the navigation pane, click ADMIN > Identity Panel > Domains.
3. On the Domains page, find the entry for the domain that you want to modify.
In the Actions column for that entry, click More > Edit.
Chapter 3. Administering

263

4. In the Edit Domain window, click the Quota tab.

5. Edit the quota values as required.
6. Click Save.
Results
A message is displayed, indicating that the quotas were saved to the domain
successfully.
Modifying the list of domain administrators:
You can add or remove users from the list of Domain Administrators to control a
domain.
About this task
To modify the list of domain administrators who are assigned to a domain,
complete the following steps:
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the navigation pane, click ADMIN > Identity Panel > Domains.
3. In the Domains page, select the entry for the domain. In the Actions column,
clickMore > Edit. The Edit Domain window opens.
4. Click the Domain Adminstrators tab.
Note: The Domain Adminstrators tab shows the following lists of users:
v All Available: Users that are members of the domain but are not Domain
Users
v Domain Administrators: Users who are Domain Administrators for the
selected domain.
5. To add a Domain Administrator, click +. The user is promoted from Domain
User to Domain Administrator for the default project only. You must manually
add the Domain Administrator user to all other projects in the domain, as
described in Modifying user assignments for a project on page 270.
6. To remove a Domain Administrator, click - . The user is demoted from Domain
Administrator to Domain User for all projects in the domain, but is not
removed from any projects.
7. Click Save.
Results
The changes you made to the list of domain administrators has been saved.
Setting a domain context:
The domain context is for Cloud administrators to refine the context that they are
accessing. Cloud administrators can limit the scope to one domain, rather than
having visibility across all domains. This allows the Cloud administrator to
identify the projects, users, groups and roles that are associated with a domain.

264

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the left navigation pane, click ADMIN > Identity Panel > Domains.
3. In the domains page, find the entry for the domain and click Set Domain
Context
Results
The domain page title changes to <domainName>:Domains. Selecting the Projects,
Users, Groups or Roles web pages will only display details for the selected
domain context.
Clearing the domain context:
Cloud administrators can clear the scope of all domains, enabling visibility across
all domains.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the left navigation pane, click ADMIN > Identity Panel > Domains.
3. In the domains page, select Clear Domain Context from the top right-hand
corner.
Results
All domains are visible.

Managing projects
You can manage the level of access for each project to IBM Cloud Orchestrator
with the user interface.

Before you begin

You must be assigned the admin role to perform these steps.
Creating a project:
You can assign individual zones to each domain in IBM Cloud Orchestrator with
the administrator user interface.
Before you begin
Set the domain context via Setting the domain context.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the projects page by clicking ADMIN > Identity Panel > Projects in the
navigation pane.
3. Click Create Project. The Create Project window is displayed.
4. Specify the name for the project.
5. Optional: Enter a description for the project

Chapter 3. Administering

265

6. Optional: By clearing the Enabled check box, you disable and cannot authorize
the domain. Selecting the Enabled check box keeps the domain enabled so that
you can authorize the domain.
7. Click Create Project.
Results
A message indicates that the project is created successfully.
Enabling a project:
Enabling a project allows you to set that project as your default project. the action
only appears if the project is disabled.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the projects page by clicking ADMIN > Identity Panel > Projects in the
navigation pane.
3. In the projects page, find the entry for the project and click More > Edit Project
in the Actions column.
4. In the Edit Project window, click the Enabled check box so that the box
contains a tick symbol.
What to do next
A message is displayed indicating that the project is enabled.
Editing a project:
You can modify the name and description of a project.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the projects page by clicking ADMIN > Identity Panel > Projects in the
navigation pane.
3. In the projects page, find the entry for the project and click More > Edit Project
in the Actions column.
4. In the Project Info tab, edit the name and description of the project.
Results
A message is displayed indicating that the project information has been modified.
Disabling a project:
Disabling a project in a domain means that users who previously had that project
set as their default cannot log in to it anymore. Other users also cannot switch to
this project anymore.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the projects page by clicking ADMIN > Identity Panel > Projects in the
navigation pane.

266

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. In the projects page, find the entry for the project and click More > Edit Project
in the Actions column.
4. In the Edit Project window, deselect the Enabled check box so that the box is
empty.
Results
A message is displayed indicating that the project is disabled.
Deleting a project:
Delete a project in the Administration user interface as the Cloud Administrator.
About this task
If a project is deleted, all of its assigned resources (virtual machines, stacks,
patterns, networks, images, and so on) remain in the cloud. Only the Cloud
Administrator can manage these orphan resources. The Domain Administrator
cannot recover from this situation.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the projects page by clicking ADMIN > Identity Panel > Projects in the
navigation pane.
3. Find the entry for the project that you want to delete. In the Actions column for
that entry, click More > Delete Project.
Note: Deleting the default project of a domain results in the domain quotas
becoming empty because the domain quotas are a multiplier of the default
project quotas. Refer to Setting the default domain quotas for more details on
the domain quotas.
Results
A message is displayed, indicating that the project has been deleted.
Assigning a zone to a project:
Assigning a zone to a project enables users within a zone to access a specific
project.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the domains page by clicking ADMIN > Identity Panel > Domains in
the navigation pane.
3. In the domains page, find the entry for the domain and select Set Domain
Context in the Actions column. The Identity Panel group is now in the context
of the selected domain and the Domains page is also changed. You are now
working within the context of the domain that you created.
4. Select Identity Panel > Projects.
5. In the Actions column in the table for the project, click More > Edit Project.
6. Click the Availability Zones tab. The available zones and the assigned zones
are listed in the following format: Zone_Name - Region_Name.
Chapter 3. Administering

267

7. To assign a zone to a domain, from the list of Available Zones, click the plus
button beside the zone name. The selected zone moves to the Assigned Zones
list. To return an Assigned Zone to an Available Zone, select the minus button
beside the zone name. Use the Filter field to search for specific zones.
8. When you have assigned all zones, click Save.
Results
A message indicates that the project is modified successfully.
Configuring project quotas:
The Cloud Administrator can configure the project quotas in OpenStack.
About this task
Log in to the Administration user interface as the Cloud Administrator. Use the
command-line interface to set the default project quotas and to change the project
quotas in OpenStack. You can specify project quotas for several different resources,
such as CPUs and memory. For more information, see the OpenStack
documentation (http://docs.openstack.org/user-guide-admin/content/
cli_set_quotas.html).
Reassigning VM instances to a project:
Reassigning VM instances to a project enables VMs which have been loaded to a
default project to be assigned to the project of a user who owns them.
Before you begin
In order to reassign instances, you must have an admin role on the source project
containing the instances to be reassigned.
Procedure
1. Log in to the Administration user interface as a Cloud Administrator.
2. In the navigation pane, click PROJECT > Instances.
3. Find the instances to be reassigned and select the check boxes beside their
names.
4. Click Reassign Instances.
Note: Reassign Instances is only visible for a VMware region.
5. Selected instances contain a list of the instances selected from the Instances
table. The following options are available:
v To deselect an instance, click on the instance in the list box. At least one
instance must be selected.
v To select all instances press Ctrl-Shift-End.
6. In the Reassign Instances window, select the Target Domain where the
instances are to be assigned.
7. Select Target Project where the instances are to be assigned.
8. Click Reassign.

268

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Results
A message is displayed indicating that the instances have been reassigned
successfully from the source domain and project to the target domain and project.
Note: When a VM instance is reassigned from one project to another, the resources
that are associated with the VM (such as networks, IPs, flavors) are owned by the
source project. If there are access issues to these resources from the new project,
you need to recreate the resources on the new project.
Customizing and extending the user interface:
Role based directory structure:
Dashboards are role based. This allows service designers to have their dashboard
extension content available to specific roles.
The directory structure that the extension content is deployed into is based on the
IBM Cloud Orchestrator roles in the following table. The four IBM Cloud
Orchestrator roles which the extension is compatible with are:
Table 32.
Name of role directory

Role

member

End User

admin

Cloud Administrator

domain_admin

Domain Administrator

catalogeditor

Service Designer

The dashboard folder is the parent extension directory. It contains a folder for each
of the four roles. It is located on the Self-service user interface server at the
following location: {server_location}/etc/dashboard
e.g. {server_location}/etc/dashboard/admin or {server_location}/etc/
dashboard/member
When a service designer wants to make a new dashboard available to an admin
user, for example, they add the extension html file to the: {server_location}/etc/
dashboard/admin directory
Navigation elements and extension naming conventions:
Naming extension files is important as these names drive the names of the
navigation elements where the dashboards are accessed from.
Navigation elements should be meaningful so that you can easily locate important
content in the UI. As these dashboard extension navigation elements are driven
from the names of the dashboard extension files, these file names should be
meaningful. Dashboard extensions appear as submenu items under the
DASHBOARD menu and take the name of the extension file as their menu label.
The label is the complete file name with any ordinal position specified and the file
extension removed.
The following table describes an example of file names and their respective menu
labels:

Chapter 3. Administering

269

Table 33.
File

Menu label

01 - Admin Extension Example.html

Admin Extension Example

02 - Member Extension Example.html

Member Extension Example

Network Dashboard.html

Network Dashboard

Performance Dashboard.html

Performance Dashboard

Ordinal numbering of extension files is included so that you can control the order
in which the extension labels appear in the DASHBOARD menu. The ordinal
numbering format convention is a number, then a hyphen (-), then the file name.
Any file name starting with this pattern is placed in this relative numbered
position in the sub menu. The pattern is stripped from the file name when
constructing the label. If an ordinal numbering format convention is not used
when naming extension files the files is added alphabetically.
Packaging and deployment:
A dashboard extension made available via the market place must be packaged as a
compressed zip or tar.gz file.
The package structure must match the role based directory structure mentioned in
the previous section. For example:
extensionExample.zip
+ dashboard
+ admin
+ 01 - My Admin Extension Example.html

To deploy the extension, extract the compressed file to {server_location}/etc. To

have the new extension content appear in the UI, restart the icoui server.
Alternatively, enter the following link in your browser to clear the navigation
cache: <scuiHostName:port>/dashboardextension/clearcache
Note: Before deploying a dashboard extension ensure that there are no extension
files that have already been deployed previously in the extension directories with
the same name. Any deployed file with the same name as one file contained in the
package will get overwritten otherwise.
Modifying user assignments for a project:
You can assign users to additional projects or update and remove assignments. You
can also specify the roles that the user will have for the project.
About this task
To modify user assignments for a project, complete the following steps:
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the navigation pane, click ADMIN > Identity Panel > Projects .
3. Click Modify Users for the project that you want to modify.
Note: The Edit Project window shows the following lists of users:
v All Users: Users who are members of the domain but are not members of
this project.

270

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Project Members: Users who are members of this project and associated
roles. This list also shows the roles that are assigned to each project member.
4. To assign a user to this project, click +. The user is moved from the All Users
list to the Project Members list.
5. To remove a user from this project, click -. The user is moved from the Project
Members list to theAll Users list.
6. To change the roles that are assigned to a project member: in the Project
Members list, expand the role list for the user, and select the roles.
7. Click Save.
Results
The changes you made to user assignments for a project has been saved.

Managing groups
You can manage the level of access for each group to IBM Cloud Orchestrator with
the user interface.
Deleting a group:
Delete one or more groups in a domain.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the groups page by clicking ADMIN > Identity Panel > Groups in the
navigation pane.
3. Find the entry for the project that you want to delete. In the Actions column for
that entry, click More > Delete Group.
Results
A message is displayed, indicating that the group has been deleted.

Managing users
You can manage the level of access for each individual user to IBM Cloud
Orchestrator with the user interface.

About this task

Note:
v When the current user password is modified, after re-login, the user is redirected
to the Edit User dialog, where the user has to click Cancel.
v You cannot remove the email address by editing a user in the Administration
user interface. To remove the email address, use the following command:
keystone user-update --email "" <USER_NAME or USER_ID>

Chapter 3. Administering

271

Creating a user:
You can manage the level of access for each user in IBM Cloud Orchestrator. Users
can be assigned to different roles on different projects.
Procedure
1.
2.
3.
4.

Log in to the Administration user interface as the Cloud Administrator.

In the navigation pane, click ADMIN > Identity Panel > Users.
Click Create User. The Create User window is displayed.
Specify the required parameters, and then click Create User.

Results
A message indicates that the user is created successfully.
Deleting a user:
You can delete one or multiple users in a domain.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. Open the users page by clicking ADMIN > Identity Panel > Users in the
navigation pane.
3. Find the entry for the user that you want to delete. In the Actions column for
that entry, click More > Delete User.
Results
A message is displayed, indicating that the user has been deleted.

Managing volumes
You can attach volumes to instances to enable persistent storage.

Procedure
1. Log in to the Administration user interface as a Cloud Administrator.
2. Click ADMIN > System Panel > Volumes.

Managing networks
As a cloud administrator you can manage networks in IBM Cloud Orchestrator
with the user interface.
Creating a network:
As a cloud administrator, you can create a new network in your environment.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. You can create a network in either of the following ways:
v To create both a network and a subnet, click PROJECT > Network >
Networks. Then, click Create Network. The Create Network window is
displayed.
You cannot specify the provider network type by using this method.

272

IBM Cloud Orchestrator 2.4.0.2: User's Guide

After you entered the required information, click Create. A message appears
indicating that the network is created successfully.
For more information, see Create and manage networks and refer to the
"Create a network" section.
v To create a network and specify the provider network type, click ADMIN >
System Panel > Networks. Then, click Create Network. The Create Network
window is displayed.
After you entered the required information, click Create Network. A message
appears indicating that the network is created successfully.
Use this method also to create networks that are shared among different
projects.
You cannot create a subnet by using this method. You can create the subnet
after the network is created by following the procedure described in Adding
a subnet to an existing network on page 274.
For more information about managing networks in OpenStack, see the
OpenStack Cloud Administrator Guide.
Note: For a VMware region, the name of the new network must match the
name of the network as defined in the vCenter Server that is being managed.
Deleting a network:
As a cloud administrator, you can delete one or multiple networks in your
environment.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the left panel, click ADMIN > System Panel > Networks. The Networks
window is displayed.
3. Select the networks that you want to delete.
4. Click Delete Networks. A confirmation window is displayed.
5. Click Delete Networks. A message appears in the top right of the screen
confirming that the networks have been deleted.
Modifying a network:
As a cloud administrator, you can edit a network to modify the name and some
options as, for example, if the network is shared among different projects.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the left panel, click ADMIN > System Panel > Networks. The Networks
window is displayed.
3. Click Edit Network on the right of the network that you want to modify. The
Edit Network window is displayed.
4. Make the required changes and click Save Changes. A message appears in the
top right of the screen confirming that the network has been updated.

Chapter 3. Administering

273

Adding a subnet to an existing network:

As a cloud administrator, you can add a subnet to an existing network.
Procedure
1. Log in to the Administration user interface as the Cloud Administrator.
2. In the left panel, click PROJECT > Network > Networks or click ADMIN >
System Panel > Networks. The Networks window is displayed.
3. Click the name of the network to which you want to add a subnet. The
Network Detail window is displayed.
4. Click Create Subnet. The Create Subnet window is displayed.
5. Enter the required information in the Subnet and in the Subnet Details tabs.
6. Click Create. A message appears in the top right of the screen confirming that
the subnet has been created.

Administering as domain administrator

Administer as a domain administrator.
A typical scenario for a Domain Administrator in a multi-tenancy environment is
the onboarding of users into the domain. The administrator assigns the users to
projects and ensures that they can deploy virtual machines and use cloud
resources.

Managing domains
Log in to the Self-service user interface as a Domain Administrator.
Click CONFIGURATION > Domain and select Domains from the menu that is
displayed, to see a list of domains that you can administer. To see more details
about a particular domain, click the domain name. You can search for a particular
instance by specifying the instance name or description in the search field. The
instance table can be sorted using any column that has the sort icon.
Domain Administrators can manage projects, groups, users, actions, offerings, and
categories. Domain Administrators can distribute the domain quotas among the
projects in their domain.
Note: Domain Administrators cannot create domains, and they cannot change the
domain quotas.
The Domain Administrator must perform the following steps to set up projects in
the domain and to grant access to cloud resources to the domain users:
1. Create a project resource.
2. Ensure that the project has access to at least a deployment availability zone.
This allows users in that project to access virtual images and deploy virtual
servers when working within this project in the logged in domain. The
availability zones that can be assigned to the project are the ones that have
been previously assigned to the domain to which the project belongs to.
3. Set the quota in the project.
4. Create and add users to the project.
These steps are detailed in Managing projects on page 275 and Managing
users on page 280.

274

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Managing projects
As a domain administrator you can manage the level of access for each project to
IBM Cloud Orchestrator with the user interface.
You can search for a particular instance by specifying the instance name or
description in the search field. The instance table can be sorted using any column
that has the sort icon.
Creating a project:
As a domain administrator you can create a new project in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Domains in the menu below the navigation menu
4. Select the check box next to the domain you want displayed in the list.
5. Click Create Project in the Actions menu. The Create Project window is
displayed.
6. Specify the name for the project.
7. Enter a description for the project
8. Optional: By clearing the enabled check box, you disable and cannot authorize
the domain. Selecting the enabled check box keeps the domain enabled so that
you can authorize the project.
9. Click OK.
Results
A new project is created.
Enabling a project:
As a domain administrator you can enable a project in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Projects in the menu below the navigation menu.
4. Select the check box next to the project you want displayed in the list.
5. Click Enable Project in the Actions menu. This option will only appear if the
project is disabled.
6. Click Confirm
Results
A window appears at the top right of the screen confirming that the project has
been enabled.

Chapter 3. Administering

275

Edit a project:
As a domain administrator you can edit a project in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Projects in the menu below the navigation menu.
4. Select the check box next to the project you want displayed in the list.
5. Click Edit Project in the Actions menu.
6. Specify the name of the project.
7. Optional: Enter a description and domain for the project. By clearing the
enabled check box, you disable and cannot authorize the project. Selecting the
enabled check box keeps the project enabled so that you can authorize the
project.
8. Click OK.
Results
A window appears in the top right of the screen confirming that the project has
been edited.
Disabling a project:
As a domain administrator you can disable a project in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Projects in the menu below the navigation menu.
4. Select the check box next to the project you want displayed in the list.
5. Click Disable Project in the Actions menu. A window is displayed asking if
you want to confirm launching the action: Disable Project.
6. Click Confirm.
Results
A window appears in the top right confirming that the project has been disabled.
Deleting a project:
As a Domain Administrator you can delete a project in a domain.
About this task
If a project is deleted, all of its assigned resources (virtual machines, stacks,
patterns, networks, images, and so on) remain in the cloud. Only the Cloud
Administrator can manage these orphan resources. The Domain Administrator
cannot recover from this situation.

276

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Projects in the menu below the navigation menu.
4. Select the check box next to the project you want deleted.
5. Click Delete Project in the Actions menu.
6. A window appears asking if you want to delete the project. Click Confirm.
Note: Deleting the default project of a domain results in the domain quotas
becoming empty because the domain quotas are a multiplier of the default
project quotas. Refer to Setting the default domain quotas for more details on
the domain quotas.
Results
A window appears at the top right of the screen confirming that the project has
been deleted.
Creating a network for a project:
As a domain administrator you can create a network for a project in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Projects in the menu below the navigation menu.
4. Select the check box next to the project you want displayed in the list.
5. Click Create Network in the Actions menu.
Note: The Create Network action in the Self-service user interface is limited to
Nova networks only. To create a Neutron network, use the Administration user
interface.
6. Select the region from the drop down menu
7. Use the following network parameters:
v Name: the name of the network
v Mask (CIDR): the definition of the IP range of the network, e.g. 10.10.10.x/24
for IP addresses between 10.10.10.1 and 10.10.10.255.
v VLAN/VXLAN ID: the VLAN ID that should be used to seperate the network
traffic from other networks, e.g. 1001.
v Bridge interface: the interface on the cloud management servers that
should be used for the bridge, e.g. eth0. Only required in regions having
nova-network configured. Not required for regions having neutron
configured.
v Gateway: the gateway of the subnet, e.g. 10.10.10.1. By default the first IP in
the range is used.
v DNS: the primary and secondary DNS servers to be used.
8. Click OK.

Chapter 3. Administering

277

Results
The network is created for and is owned by the selected project. Only members of
the project can use the network.
Deleting a network from a project:
As a domain administrator you can delete one or multiple networks from a project.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3.
4.
5.
6.
7.

Click Projects in the menu below the navigation menu.

Select the check box next to the project you want displayed in the list.
Click Delete Network in the Actions menu.
Select the network you want to delete.
Click OK.

Results
The network is deleted from the region it has been created.
Modify the availability zones of a project:
As a domain administrator you can grant and revoke access of availability zones to
a single project in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
In the navigation menu, click CONFIGURATION > Domain.
Click Projects in the menu below the navigation menu.
Select the check box next to the project you want displayed in the list.
Click Modify Availability Zones in the Actions menu. The Availability Zones
of Domain and the Availability Zones of Project are listed in the following
format: Availability_Zone Region.
6. Complete one or more of the following options to modify the user availability
zones of a project:
2.
3.
4.
5.

v To assign a zone to a domain from the list of Availability Zones of Domain,

select an availability zone by selecting the check box beside it, then click the
>> button. The selected zone moves to the Availability Zones of Project list.
v To return an Availability Zone of Project to an Availability Zone of
Domain, select an availability zone by selecting the check box beside it, then
click the >> button beside the zone name.
7. Click OK.
Results
The changes you made to the availability zones of the project has been saved.

278

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Modify the quota of a project:

As a domain administrator you can modify the quota of a single project in a
domain.
Procedure
1.
2.
3.
4.
5.
6.
7.

Log in to the Self-service user interface as a Domain Administrator.

In the navigation menu, click CONFIGURATION > Domains.
Click Projects in the menu below the navigation menu.
Select the check box next to the project you want displayed in the list.
Click Modify Quota in the Actions menu.
Select the region from the drop down menu.
Click Next.

8. The quota dialog box contains values for the number of cores, the number of
instances, amount of memory and the number of floating Ips. Enter a value for
each.
Note: The sum of all project quota of a domain can not exceed the overall
quota of the domain. The validate button checks if that condition is met. If the
condition is not met, the quota can not be changed. To view the overall domain
quota and the quota remaining in the domain, click Show Domain Quota.
9. Click OK.
Results
The changes you made to the quota of the project has been saved.
Modifying users in a project:
As a domain administrator you can add and remove users of a single project in a
domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Projects in the menu below the navigation menu.
4. Select the check box for the project that you want to edit.
5. In the Actions menu, click Modify Users.
Note: The Modify Users page shows the following lists of users:

6.
7.
8.
9.

v Users in Domain: Users in the current domain who are not assigned to the
selected project.
v Users in Project: Users assigned to the current project, with roles assigned.
The user roles are also shown.
To assign a user to a project, select the check box beside the user, then click >>.
The selected user moves to the User in Project list.
To remove a user from a project, select the check box beside the user, then click
<<. The selected user moves to the Users in Domain list.
To edit the role assignment of a user in the User in Project list, click the Role
column for the user. Select one or multiple roles from the roles list.
Click OK.
Chapter 3. Administering

279

Results
The changes you made to user roles and user assignments for a project have been
saved.

Managing users
As a domain administrator you can manage the level of access for each individual
user to IBM Cloud Orchestrator with the user interface.
You can search for a particular instance by specifying the instance name or
description in the search field. The instance table can be sorted using any column
that has the sort icon.
Creating a user:
As a domain administrator you can create a new user in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Domains in the menu below the navigation menu.
4. Select the check box next to the domain you want displayed in the list.
5. Click Create User in the Actions menu. The Create User window is displayed.
6. Specify the name for the user, the default project to assign the user to and the
users role in that project.
7. Optional: Enter an email, password and domain for the user. By clearing the
enabled check box, you disable and cannot authorize the user. Selecting the
enabled check box keeps the user enabled so that you can authorize the project.
8. Click OK.
Results
A new user is created and appears in the User view. This action applies only to a
single domain.
Deleting a User:
As a domain administrator you can delete one or multiple users in a domain.
Procedure
1. Log in to the Self-service user interface as a Domain Administrator.
2. In the navigation menu, click CONFIGURATION > Domain.
3. Click Users in the menu below the navigation menu.
4. Select the check box next to the user you want displayed in the list.
5. Click Delete User in the Actions menu.
6. Click Confirm in the window that opens
Results
A window appears in the top right of the screen confirming that the user has been
deleted.

280

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Auditing
IBM Cloud Orchestrator provides a comprehensive auditing function to help you
maintain the security and integrity of your environment. This topic introduces you
to the auditing capabilities, the business value of auditing, and procedures for
working with the event log.

Capabilities overview
The auditing function is essentially a continuous logging activity; IBM Cloud
Orchestrator records information about administrative and security-related events
that occur in the product and in the cloud.
The following list displays a few examples of the events that are tracked by the
auditing function:
v configuration changes
v user authentication
v attempts to access objects that are secured by object-level access control
v digital signature validation
For each event, the collected information identifies the user who initiated the
operation, and whether it succeeded. IBM Cloud Orchestrator makes this audit
data available for download in the form of event records.
Login actions are logged separately from the other events. For information about
auditing login actions, see Auditing login on page 282.

Business value
With these capabilities you can protect your environment from both internal and
external security threats. Use the audit data to identify suspicious user activity, and
then hold those users accountable for their actions. In the case of an attempted
security attack, analysis of the audit data can help you determine if and how your
infrastructure was compromised. Based on that information, you can strategize the
most effective defensive measures.
The auditing function also helps your organization to comply with regulatory laws
such as the Health Insurance Portability and Accountability ACT (HIPAA) and the
Sarbanes-Oxley (SOX) Act. These laws mandate formal practices not only for
protecting data and detecting fraud, but also for documenting your efforts to do
so. The audit data provides that evidence; with IBM Cloud Orchestrator you have
numerous options for downloading the data in a manner that suits your business
processes.
For detailed information on how to exploit the business value of audit event
records, see Audit event record attributes and usage tips on page 282.

Working with the event log

The IBM Cloud Orchestrator event log stores the event records that contain audit
data. To download the records, you can use any direct calls to the REST API. Note
that for working with this API, IBM Cloud Orchestrator provides sample scripts
that you can customize and run with a job scheduler to automate download of
audit data on a regular basis. See Download options for audit event records on
page 286 for more information.
Chapter 3. Administering

281

After you download records from the log and store them in your own archives,
you must delete those same records from the log. Otherwise, when the log reaches
a pre-set capacity limit, IBM Cloud Orchestrator suspends the auditing function
until storage frees up. When consumption nears 90%, clean the audit log storage.
See Deleting audit data to free storage on page 290 for more information.
Best practice: Designate one individual with admin role to download audit data,
archive it to external storage, and then delete it from the Workload Deployer
component machine as a routine process.

Auditing login
When a user tries to log in to the Self-service user interface, the login action is
logged for auditing purpose.
If the login fails, also the failure reason is logged.
The login actions are logged in the /var/log/scoui.log file on Central Server 2,
with the other log messages related to the Self-service user interface. You can find
the messages related to the login actions by searching for the login string.
Example of messages related to login actions:
[2015-04-13 15:36:57,892] [qtp-380990413-64] [INFO] n3.app.handler.action.LoginHandler
Successful login: for user admin
...
[2015-04-13 15:37:38,764] [qtp-380990413-66] [INFO] n3.app.handler.action.LoginHandler
Failed login: Invalid credentials for user admin
...
[2015-04-13 15:38:00,192] [qtp-380990413-55] [INFO] n3.app.handler.action.LoginHandler
Failed login: No password provided for user admin

Audit events
With the IBM Cloud Orchestrator auditing function, you collect data about specific
types of user activity, security events, and configuration changes on the product
and in the cloud. That audit data can help you detect and analyze potential
security breaches, or other misuse of cloud resources.

Event records
IBM Cloud Orchestrator collects audit data about events in event records; one record
corresponds with each event. For descriptions of event record attributes and an
understanding of how to analyze the attribute values, see Audit event record
attributes and usage tips.

Audit event record attributes and usage tips

Use this article as a reference aid for exploiting the business value of your audit
data. The following sections define the record attributes, show examples of
attribute values, and provide guidelines for using the attributes to analyze
questionable or malicious user behavior in your IBM Cloud Orchestrator
environment.

Record structure overview

The product captures data about each audit event in an event record, in
comma-separated value (CSV) format. The first eight comma-separated elements of
every record are values for the common attributes that are listed in Table 1 of the
next section. Within each record, the values for these common attributes are

282

IBM Cloud Orchestrator 2.4.0.2: User's Guide

followed by attribute name-value pairs that can vary from record to record. Table 2
in Attribute name-value pairs lists the pairs that you can use in your analysis of
cloud activity.

The eight common attributes

Table 1 provides the attribute definitions that apply to the first eight values in
every event record. All of these attribute values appear in the same order in every
record, and all of them are strings.
Table 34. Universal event record attributes
Order of appearance in record

Attribute

Product version

Definition
Version of the IBM Cloud Orchestrator product

Timestamp

Time (in UTC time zone) when the event record was generated

Resource type

Type of resource on which an action was attempted

Action

Action that was attempted on the specified resource

Resource ID

Resource instance number

Resource name

Name of the specified resource instance

User

Who attempted to perform the specified action

Client IP address

IP address from which the action was initiated

Attribute name-value pairs

Table 2 depicts attributes that are not common to all event records because the data
is not applicable to every audit event.
Note: You might see event records with attribute name-value pairs that are not
listed in this table. Do not include those unlisted attributes in your analysis of
audit data. They are subject to change in future releases of IBM Cloud
Orchestrator.
Table 35. Attribute name-value pairs
Attribute name

Data value example

Description

event_authz_acl_check

/admin/users/u-0/
userdata.json_RWF_true

Indicates that a user with an appropriate permission

(read, write, or full access permission) successfully
accessed the specified resource, which in the data
value example is /admin/users/u-0/userdata.json.
When a user accesses multiple resources within an
audit event, the product concatenates those resource
names in the attribute value. For example:
/admin/users/u-0/userdata.json_RWF_true___/
admin/plugins/webservice/1.0.0.3/parts/
webservice.scripts.tgz_WF_true

event_authz_check

success, failure, or reject

Shows the result of a REST interface access control

check.
When performing this verification step, the product
verifies every access request against a set of rules.
These rules entail verifying the endorsement
signature, the freshness of the request timestamp, the
integrity of the security token, and the sufficiency of
the caller and asserted security roles.

Chapter 3. Administering

283

Table 35. Attribute name-value pairs (continued)

Attribute name

Data value example

Description

event_authz_header

[{"attributes":
"{\"authorizationAttributes\":
. . . }
| {"attributes":
"{\"authorizationAttributes\":
. . . }]

Displays a stack of one or more security tokens that

represent requester security credentials.
Overview of the stack structure:
v The first token of a stack is known as the caller
security token, or caller token, and represents the
security credentials of the requesting user. (The
caller token is the only token in a single-token
stack.)

Values for the event_authz_header

attribute can include multiple
elements, which are security
tokens in the form of JSON objects. v Each subsequent token represents an intermediate
server that relayed the request on behalf of the
Thus, to accommodate the CSV
original caller. These tokens are endorsement security
format of the overall record,
tokens, or endorsement tokens.
multiple tokens within this
attribute value are separated by
v Altogether, the caller token and endorsement
vertical bars (|) rather than
tokens of a multi-token stack represent the path
commas.
that a request travelled to reach a resource.
Note: The last security token in the stack
Note that the objects in this
represents the most recent endorsement server,
particular data value example are
which can assert additional security roles, if
abbreviated. See the "Security
necessary, when making downstream request
token format" section that follows
invocations.
this table for a complete example
of a token.
event_exception

CWZSE0924W: User: user1 not

found

Specifies the error condition that has caused a request

failure or rejection.

event_outcome

success, failure, or reject

Indicates whether the overall request process was

successful, a failure, or rejected.

event_request_remote

192.0.2.4_192.0.2.4_52917

Displays the requester host name, IP address, and

port number.

event_request_url

https://workload_deployer:9444/
sts/admin/registries

Specifies the request URL.

event_roles

[REPORT_READER]_[AUDIT_READER]
_[AUDIT_WRITER]

Lists the security roles of the specified user. The list

consists of security roles that have been granted to
the user, as well as any additional security role that is
asserted by the most recent endorsement server. Refer
to the description of the envent_authz_header
attribute for more information about endorsement
servers.

event_subjects

[user1]

Displays the security identity of the requester.

In cases where an intermediate server makes
downstream requests on behalf of a user, the
event_subjects attribute tracks the chain of requester
identities. For example, the value [user1]_[cbadmin]
indicates that an intermediate server assumed the
cbadmin security identity to make a request on
behalf of the original requester user1.

Security token format

As mentioned previously, the event_authz_header attribute displays IBM Cloud
Orchestrator security tokens as signed JSON objects. Review the following example
for an understanding of the data that these security tokens contain. (Note that the
security token format is subject to change in future releases of the product.)

284

IBM Cloud Orchestrator 2.4.0.2: User's Guide

{ "attributes":
"{ "authorizationAttributes" : { "groups" : ["g-0"],
"roles" :
["11","13","14","15","16","17","1","2","3","4","5","6","7","8","9","10"] },
"ownerProcessTypeID" :"IT",
"ownerPublicKey": "IT",
"AT" : "1316453354588",
"userName" : "cbadmin",
"userID" : "u-0",
"type": "user",
"issuerProcessTypeID" : "TS",
"expirationTime" : 86400000,
"issuerPublicKey" : "TS"
}",
"signature":"IPf***A=="}

Guidelines for analysis

Ultimately, the business value of audit data analysis is to minimize risk to your
business assets, by maintaining the integrity of your IT practices and building
effective security measures for your environment. The following guidelines and
analysis scenarios give you insight to achieve those critical goals.
v Detect fraudulent or risky user activity, and take action to preserve system
integrity Use event record attributes to track the activity of both human and non-human
user entities. (Remember that a user entity might not be a human, but rather a
system such as a deployed virtual machine.) For example, you might want to
track the recent activity of a specific user on a specific resource. You can search
event records with attributes that meet all of the following conditions:
A User value that matches a specific user security identity
Values for Resource type, Resource Name, and, optionally, Resource Id that
match your resource of interest
Timestamp values that correspond with your time frame of interest
If you examine the records and find user behavior that potentially compromises
your environment, you can hold the offender accountable. If the user in question
is actually a non-human user entity, you can make configuration modifications
to minimize risk.
v Analyze security attacks to provide insight for proactive security measures Use attributes to perform detailed intrusion detection and forensic analysis if an
attack occurs. The attributes event_subjects, event_authz_header, and
event_authz_acl_check are particularly helpful for these purposes. The following
list enumerates the ways in which you can use the attributes:
The event_subjects attribute shows the complete path of a user's request to
access a resource; use it for a quick analysis of how a malicious user might
have launched his or her attack.
You can also use event_subjects to determine which records require detailed
examination. Consider the attribute as a concise summary of the security
token stack information in the event_authz_header attribute. Therefore, you
can use event_subjects to pinpoint the event records that need to be
analyzed meticulously with the information in event_authz_header.
You can use the Resource Type and Resource Name attributes to identify
records that document activity on a resource of particular concern. Then you
can examine the event_authz_acl_check attribute for more detailed
information about the user who accessed that resource. Consider the
following sample event_authz_acl_check value:
Chapter 3. Administering

285

/admin/plugins/webservice/1.0.0.3/parts/webservice.scripts.tgz_WF_true

This value indicates that the user who accessed the resource
/admin/plugins/webservice/1.0.0.3/parts/webservice.scripts.tgz has write
and full permissions for that resource. Thus, when the integrity of a resource
is compromised, you can refine your list of suspected perpetrators to users
who have write and full permissions for the resource in question.
Based on these tips and illustrations, you can plan other ways to use the rich audit
data that IBM Cloud Orchestrator provides to protect your environment and,
consequently, your business data.

Download options for audit event records

You can download audit event records by using the REST API. The records that
you request are provided in comma-separated value (CSV) format (wherein the
attribute values of each record are separated by commas).

File names
You can specify the name of the .zip file to which your records are written for the
download operation.

Additional files and content

Table 36. Download options for audit data
Download option

Files that you receive

Link to download instructions

REST API

XXX.zip, where XXX is a name that you specify by parameter. This .zip file contains:

Retrieving audit data with the

REST API
Note: For working with the REST
API, IBM Cloud Orchestrator
provides sample scripts that you
can customize and run with a job
scheduler to automate download of
audit data on a regular basis.

v audit-events.csv - This file contains the audit event records that you specified, in CSV
format.
v audit-events-signed-events-checksum - Contains the digital signature that verifies both
the integrity and authenticity of your audit data.
v audit-events-record-IDs
v audit-events-signed-record-IDs

Retrieving audit data with the REST API

For retrieving audit event records with the REST API, IBM Cloud Orchestrator
provides sample scripts that you can customize and run with a job scheduler to
automate downloads on a regular basis. The REST API returns the event records in
comma-separated value (CSV) format, in a .zip file.

Before you begin

Working with the auditing resources and scripts entails the following prerequisites:
v You need an environment that supports shell scripts, Python, Java, Curl, and a
file archiving utility (for manipulating .zip files). For example: Cygwin, a
compatibility layer, meets all of these requirements.
v All of the scripts are located in CLI directories.
v You must have the admin role in IBM Cloud Orchestrator.
You also might want to review general information about the REST API in the
article REST API reference on page 867. For this particular procedure, you need
to understand that invocation of the API is accomplished through HTTP requests.

286

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

Table 1 lists the sample scripts that you can use to download the .zip file of audit
data and unzip it. The following procedure steps provide guidelines for using the
scripts.
Table 37. Overview of sample scripts
File name

Functional description

Location

create_basicauth_header.py

This Python script is used by the following Curl script to create

an HTTP basic authentication header with your user key
information (your IBM Cloud Orchestrator credentials).

...\deployer.cli-XXX\deployer.cli\lib\XXX\
deployer, where XXX is the version number of
the CLI

cscurl.sh

This shell script performs the following tasks:

...\deployer.cli-XXX\deployer.cli\lib\XXX\
deployer, where XXX is the version number of
the CLI

v Runs the create_basicauth_header.py script to create the

authentication header.
v Issues a Curl command to IBM Cloud Orchestrator with the
authentication header to authenticate your credentials. The
Curl command targets the URL of the IBM Cloud Orchestrator
component that provides the audit-related REST API.
v Sends the HTTP request for downloading the audit data to the
REST API.
Note: You must specify the HTTP request as a parameter of
cscurl.sh.
auditFetch.sh

This sample script provides a very simple demonstration of how ...\deployer.cli-XXX\deployer.cli\samples,

you can automate the entire process, and thus adopt it as another where XXX is the version number of the CLI
job that you run regularly in your IT organization.

Steps 1 - 5 are preparatory steps for using these scripts. Steps 6 - 7 describe how to
use cscurl.sh to download audit data in a .zip file, and then unzip that file. Step 8
describes how to use auditFetch.sh. The auditFetch.sh script invokes both of the
other scripts to automate the download and unzip operations. Consider it as a
model for code that you can run with a job scheduler to regularly download audit
data.

Procedure
1. Place the scripts in an appropriate working directory.
2. Download your IBM Cloud Orchestrator user keys from the product and save
them in the same directory that contains the scripts.
a. Open a browser window and go to https://Workload_Deployer_server/
resources/userKeys/.
b. Type your user name and password in the authentication fields.
c. Select the directory and provide a file name for storing your keys.
d. Save the keys as a .json file.
3. Optional: For added security in a production environment, you can use the
IBM Cloud Orchestrator root certificate to authenticate the scripts to the REST
API. Follow these steps to download the certificate and save it in the same
directory that contains the scripts and your user keys:
a. Open a browser window and go to https://Workload_Deployer_server/
resources/rootcacertificate/.
b. Select the directory and provide a file name for storing the root certificate.
Note that the default file name is cert.pem.
c. Save the root certificate.
4. Optional (but necessary if you want to use the root certificate for
authentication): In the /etc/hosts file of your workstation, bind the IP address
of your IBM Cloud Orchestrator to the name that is used in the root certificate,
IBMWorkloadDeployer.
Chapter 3. Administering

287

5. Construct the URL for the download request that the cscurl.sh script sends to
the REST API; you must provide this URL as a parameter to run cscurl.sh in
the next step.
You can choose between two options for downloading your audit data. The
more basic option is to specify a maximum number of records to download.
Alternatively, you can specify both a maximum number of records and the time
frame in which the product logged those records. For either option, the URL
must include the location of the REST API code that downloads the data and
the resource name of the option that you choose. Use the following models for
your URL:
v To simply specify a maximum number of records in the request, construct a
URL for the events resource and use the size parameter:
https://Workload_Deployer:9444/audit/archiver/events?size=X

For the X variable, substitute the number of records that you want to
download. You can request up to 20,000 records. If you specify a greater
number, the product automatically resets your request to 20,000 records, and
ultimately writes that number of records to the .zip file.
v To add a time frame to your request, construct a URL for the filteredEvents
resource and specify the start and end times as Epoch timestamps. (Use the
time conversion tool of your choice to convert your desired date and times
into Epoch timestamps.)
https://Workload_Deployer:9444/audit/archiver/filteredEvents?size=X
&startTime=long_value&endTime=long_value

Note: If you did not perform Steps 3 - 4, replace the name

Workload_Deployer in the URL with the IP address of your IBM Cloud
Orchestrator server.
6. Run cscurl.sh with parameters that specify the URL that you created in Step 5,
as well as the name of the .zip file in which you want the REST API to store
the audit data. For example:
./cscurl.sh username=user1 password=user1
keyfile=userKeys.user1.json -v --cacert root_cert.pem
-H "Accept:application/octet-stream"
"https://IBMWorkloadDeployer:9444/audit/archiver/events?size=X"
> ArchiveFetchTempFile

Note all of the variables that represent parameter values in the statement:
v user1 = the user name
v user1 = the user password
v userkeys.user1.json = the file that contains the user keys
v root_cert.pem = the name of the file that contains the IBM Cloud Orchestrator
root certificate
v X = the number of records to be downloaded
v ArchiveFetchTempFile = the name of the .zip file to which the audit data is
written
Also, be aware of the following usage notes for running cscurl.sh:
v To use the script to send a request for the filteredEvents resource (to
retrieve event records that the product logged within a specific time frame),
encapsulate the URL in single quotes rather than double quotes.
v Running cscurl.sh without parameters triggers display of its help message.
v To guard against data loss, you must specify a file for the audit data.
Otherwise, the script returns it as simple command-line output.

288

IBM Cloud Orchestrator 2.4.0.2: User's Guide

7. Unzip the archive file that is returned from the REST API. (In response to the
previous example of running the script, the REST API would return
ArchiveFetchTempFile.zip.) Consequently you now have four files, as depicted
in the following list.
v audit-events.csv - Contains your audit event records in CSV format.
v audit-events-signed-events-checksum - Contains the digital signature that
verifies both the integrity and authenticity of your audit data. Archive this
file along with your event records.
v audit-events-record-IDs
v audit-events-signed-record-IDs
Note: The last two files contain data that you must send back to the REST
API to delete the event records from the Workload Deployer machine (to free
storage resources). See the "What to do next" section of this article for more
information about deleting audit data.
At this point the retrieval process is complete. If you followed Steps 1 - 7, you
successfully used the individual scripts and the REST API to write your audit
data to a .zip file and download it. Step 8 describes auditFetch.sh , which
automates the entire process; the script provides an example of code that you
can run with a job scheduler to regularly download audit data.
8. To run auditFetch.sh, use the following statement as a model:
./auditFetch.sh username=auditor password=auditor
keyfile=userkeys.auditor.json IWD=IP address size=X > ArchiveFetchTempFile

Tip: If you performed Steps 3 - 4 in order to use the root certificate to

authenticate with the REST API, modify the script's invocation of cscurl.sh as
follows: Replace the -k option with the -v --cacert options. Remember to
specify the name of the file in which the IBM Cloud Orchestrator root
certificate is stored on your workstation, as in: -v --cacert cert.pem. Then
when you type the statement to run auditFetch.sh, change the value of the IWD
parameter to the name IBMWorkloadDeployer.
Based on the values that you supply for the parameters, auditFetch.sh
performs these tasks to download your audit event records:
v Authenticates your credentials with IBM Cloud Orchestrator.
v Constructs an HTTP request for X number of records and sends it to the
REST API. (If you do not specify a particular number of records with the
size parameter, the REST API returns a maximum number of 20,000 records.)
v Stores the records that are retrieved by the REST API in a .zip file with the
name that you specified. (If you do not specify a file name, the script uses
the default name of ArchiveFetchTempFile.zip.)
v Unzips that archive file, which contains the following files:
audit-events.csv - Contains your audit event records in CSV format.
audit-events-signed-events-checksum - Contains the digital signature
that verifies both the integrity and authenticity of your audit data. Archive
this file along with your event records.
audit-events-record-IDs
audit-events-signed-record-IDs
Note: The last two files contain data that you must send back to the REST
API to delete the event records from the Workload Deployer machine (to free
storage resources). See the "What to do next" section of this article for more
information about deleting audit data.
Chapter 3. Administering

289

Be aware of the following usage notes for running auditFetch.sh:

v Running this script without parameters triggers display of its help message.
v In some environments, such as Ubuntu, you might need to modify the
script's invocation of cscurl.sh; add the period and forward-slash characters
(./) as a prefix to the statement that invokes cscurl.sh.

What to do next
Because IBM Cloud Orchestrator does not automatically delete audit data after you
download it, you must run the auditDelete.sh script to delete the data from the
Workload Deployer machine and free storage resources. You can use this script
along with your customization of auditFetch.sh as part of a regularly scheduled
job to download, archive, and then delete audit data. See the article Deleting
audit data to free storage for information about auditDelete.sh.

Deleting audit data to free storage

To help safeguard your auditing processes, IBM Cloud Orchestrator does not
automatically delete audit event records from the event log after you download
them. Instead, you must delete the records from the log in order to free storage on
the Workload Deployer machine. This article describes how to delete event records
with the auditDelete.sh script, which exploits the IBM Cloud Orchestrator REST
API.

Before you begin

v Understand that when audit data storage reaches a pre-set capacity limit on the
machine where the Workload Deployer component has been installed, IBM
Cloud Orchestrator suspends collection of audit data until the storage resources
free up. Therefore, it is recommended that you delete audit data from the event
log immediately after you download the data and archive it, preferably in a
routine job. If you choose not to adopt this best practice, always remove the
oldest record sets first when you clean the audit log.
v Also consider these other best practices for deleting audit data from the
Workload Deployer machine:
Designate one individual with admin role to download audit data and
subsequently delete it from the Workload Deployer machine.
Do not run download and delete operations concurrently.
v You need an environment that supports shell scripts, Python, Java, and Curl. For
example: Cygwin, a compatibility layer, meets all of these requirements.
v The auditDelete.sh script is located in the deployer.cli samples library.
v Finally, you must have the admin role to delete audit event records.

About this task

When you run auditDelete.sh, you clean up specific record sets that you have
already downloaded from the Workload Deployer machine; you identify these
record sets with the parameters that you specify for the script.
Note: the auditDelete.sh script needs cscurl.sh and cscurl.sh requires
create_basicauth_header.py to run. Therefore, these files (cscurl.sh and
create_basicauth_header.py) must be in the same folder as the script. If you want
to use this sample script, you must manually copy the required files from the
library.

290

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. Locate the auditDelete.sh script in the samples library of the IBM Cloud
Orchestrator command-line interface (CLI). The directory path is
...\deployer.cli-XXX\deployer.cli\samples, where XXX is the version
number of the CLI. Copy the script to another directory if you wish.
2. Download your IBM Cloud Orchestrator user keys from the Workload
Deployer machine and save them in the same directory that contains the
auditDelete.sh script.
a. Open a browser window and go to https://
your_workload_deployer_server/resources/userKeys/.
b. Type your user name and password in the authentication fields.
c. Select a directory and provide a file name for storing your keys.
d. Save the keys as a .json file.
3. To run the script, use the following statement as a model:
./auditDelete.sh username=auditor password=auditorpswd
keyfile=userkeys.auditor.json IWD=your_workload_deployer_server
map=record_IDs hash=signed_hash

Note all of the variables that represent parameter values in the statement:
v auditor = Your user name
v auditorpswd = Your user password
v userkeys.user1.json = The file that contains your user keys
v your_workload_deployer_server = IP address of the machine where the
Workload Deployer component has been installed.
v record_IDs and signed_hash - Both variables, which represent values for the
parameters map and hash, identify the record set to be deleted from the
Workload Deployer machine. These parameter values name two files that
were products of a previous download operation, and were included in your
audit-events.zip file. Define the parameters as follows:
For the map parameter, specify the name of the file that lists the IDs of the
records that you downloaded. It was included in your downloaded .zip
file as audit-events-record-IDs.
For the hash parameter, specify the name of the file that contains the
signed hash of the record IDs. It was included in your downloaded .zip
file as audit-events-signed-record-IDs.
However, you do not need to specify the map and hash parameters if all of
the following conditions are true:
You are deleting records that you just downloaded from the Workload
Deployer machine.
You have not changed the name of either audit-events-record-IDs or
audit-events-signed-record-IDs.
You have placed both files in the same directory as auditDelete.sh.

Results
You have now deleted the previously downloaded audit event records from the
Workload Deployer machine.

Chapter 3. Administering

291

What to do next
Review the article Audit event record attributes and usage tips on page 282 for
an understanding of how you can best exploit IBM Cloud Orchestrator event
records in your auditing analyses.

Password management
There are two ways of managing your password in IBM Cloud Orchestrator.

Changing the password

You can change your password by using the Administration user interface.

About this task

This procedure describes how to change the password of general users. For special
users, additional steps might be necessary. For information about changing the
password of special users, such as admin, see Changing the various passwords
on page 127.

Procedure
1. Log in to the Administration user interface as a Cloud Administrator.
2. In the upper-right corner of the window, you can see the name of the current
project, the current region, and the current user. Click the name of the current
user, and click Settings to display the User Settings page.
3. In the navigation pane on the left, click SETTINGS > Change Password.
4. In the New password and Confirm new password fields, enter the new
password.
5. Click Change.

Results
The password is changed successfully.

Resetting a password
You can reset a forgotten password using the keystone command line interface
tool.

Procedure
1. As root log onto Central Server 1.
2. Source the keystonerc file by running the following command: source
keystonerc.
3. Use the keystone user-get command to see the unique id related to the user
whose password you want to change.
4. Once you have the id, use the keystone user-password-update command to
reset the password. The format of the command is as follows : keystone
user-password-update [--pass <password>] <userId>. The password parameter
is the password you want to update to. The userId is the unique user Id
retrieved from the user-get command

Results
The password has been reset.

292

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 4. Managing orchestration workflows

Create custom orchestration workflows in the Business Process Manager user
interface and run them in your IBM Cloud Orchestrator environment.

Orchestration workflows
An orchestration workflow, which is based on Business Process Manager Business
Process Definition, defines a logical flow of activities or tasks from a Start event to
an End event to accomplish a specific service.
You can use the following types of orchestration workflows:
v Managing offerings on page 325: These workflows are used to define the
offerings that cloud users can select in the Self-Service Catalog. They include
user interface and the service request flow.
v Managing actions on page 327: These workflows are used to define IBM
Cloud Orchestrator actions. They include user interface and the action flow.
v Orchestration actions for Virtual System Patterns (Classic) on page 294:
Orchestration actions are provided for backward-compatibility with IBM
SmartCloud Orchestrator v2.3. These workflows are used to define additional
Orchestration actions for Virtual System Patterns (classic).
The service can be started either by events triggered by IBM Cloud Orchestrator
management actions or by user actions in the IBM Cloud Orchestrator user
interface. The activities that comprise the service can be either scripts (JavaScript),
Java implementations, web services or REST calls, human tasks, and so on. They
can be either executed in sequence or in parallel with interleaving decision points.
Each activity within an orchestration workflow has access to the cloud
environment data in the form of the OperationContext object, which is passed as
input parameter to each orchestration workflow. The operation context is an
umbrella object that contains all data that is related to the execution of an
operation. The operation context object must be defined as an input parameter
variable for all business processes that are started as an extension for an IBM
Cloud Orchestrator operation. Human services must define the operation context
ID as an input parameter and as a first activity, must retrieve the operation context
object with its ID. The operation context object contains metadata information, for
example:
v User
v Project
v Event topic
v Status
It also contains information about the instance in which the orchestration workflow
is executed, for example:
v Type
v Status
v Virtual system ID
v Virtual system pattern ID
v Virtual application ID
Copyright IBM Corp. 2013, 2015

293

v Information about the virtual machines that belong to the instance - CPU,
memory, disk space, and so on.
For more technical details about the operation context object, see the IBM Cloud
Orchestrator Content Development Guide.
Workflows can throw error events or post-status messages, which are then shown
in the IBM Cloud Orchestrator user interface. For more information about errors,
see the IBM Cloud Orchestrator Content Development Guide.
An orchestration workflow can also have additional user interface panels in order
to collect data that is needed as input. These panels are also implemented based on
workflow technology, and they are called human services in Business Process
Manager.

Self-service offerings
Self-service offerings are typical administrative actions that are used to automate
the configuration process.
Offerings, like actions, are custom extensions to IBM Cloud Orchestrator. You can
develop these extensions by using Business Process Manager Process Designer, and
then add them as offerings in the CONFIGURATION tab in the IBM Cloud
Orchestrator Self-service user interface. An offering can consist of:
v A Business Process Manager business process defining the activities to be
performed by the extension.
v User interface panels that collect additional data, implemented by a Business
Process Manager human service (optional).
Users access offerings in the SELF-SERVICE CATALOG tab, where they are
grouped into categories.
Related tasks:
Designing self-service on page 324
A Service Designer can manage the artifacts in the Self-Service Catalog, and use
them to customize the IBM Cloud Orchestrator environment. A Service Designer is
a user with the catalogeditor role.

Orchestration actions for Virtual System Patterns (Classic)

Orchestration actions refer to actions that are run on virtual system instances only.
Click PATTERNS > Pattern Design > Orchestration Actions to create, modify or
delete Orchestration Actions. There are two types of Orchestration Actions, User
actions and Event-triggered actions. Orchestration Actions are user actions or
event-triggered actions. You can initiate user actions with the More Actions menu
available in the instance view for virtual systems (classic). Event-triggered actions
can be called during the deployment cycle of virtual systems (classic) at various
points so that the deployment process can be customized, enhanced or overridden
in some way.

294

IBM Cloud Orchestrator 2.4.0.2: User's Guide

User actions
User actions are custom actions that can be run on virtual system instances.
User actions implement additional lifecycle management actions which extend the
set of predefined actions.
To view the list of all available user actions click PATTERNS > Pattern Design >
Orchestration Actions. Within this view you can also add new actions and modify
or delete existing actions. To search for an action enter the action name or
description in the search field.

Event-triggered actions
Event-triggered actions are Business Process Manager business processes that are
triggered by a specified event during a predefined management action for a classic
virtual system.
To view the list of all available event-triggered actions, click PATTERNS > Pattern
Design > Orchestration Actions. Within this view you can also add new actions
and modify or delete existing actions. To search for an action enter the action name
or description in the search field. You can customize event-triggered actions to run
during events that are called plug points. The plug points are categorized based on
actions during which they occur:
v Deployment or undeployment of a pattern:
Before provisioning
After provisioning
Before start of virtual system instance
Before virtual system instance deletion
After virtual system instance deletion
v Server actions, like Start, Stop, Delete, and Modify Server Resources:
Before the instance status changes to start
Before the instance status changes to stop
After the instance status changes to start
After the instance status changes to stop
Before the server status changes to start

Before the server status changes to stop

After the server status changes to start
After the server status changes to stop
Before the server status changes to delete
After the server status changes to delete

Note: A user interface must not be defined if the related pattern is handled via a
self-service offering

Chapter 4. Managing orchestration workflows

295

Samples and standard extensions for orchestration workflows

IBM Cloud Orchestrator provides an easy way to build the most common types of
workflows. No programming is required. With IBM Process Designer, a graphical
tool to build workflows, and the pre-built samples and templates, you can create
your own workflows with simple drag and drop editing, and attach common types
of automation routines that are widely available.

Pre-built samples
IBM Cloud Orchestrator includes a set of toolkits that contain templates that you
can reuse and adapt to your needs.
The SCOrchestrator_toolkit provides the essential building blocks, which are
needed to build Business Process Manager business processes and human tasks,
which are then used as extensions for IBM Cloud Orchestrator.
Note: This toolkit and all the other provided toolkits can be found in Developing
IBM Cloud Orchestrator content.
You can also search for additional samples in the IBM Cloud Orchestrator Catalog
at https://www-304.ibm.com/software/brandcatalog/ismlibrary/
cloudorchestratorcatalog#. IBM Cloud Orchestrator Catalog is a platform and
one-stop-shop for IBM customers, partners, and employees, where developers,
partners, and IBM Service teams continuously share content among one another.

Advanced programming
To create more sophisticated automation, involving richer programming languages,
see Developing IBM Cloud Orchestrator content.

Working with Business Process Manager

You can use Business Process Manager processes to extend the capabilities of IBM
Cloud Orchestrator.

About this task

Business Process Manager provides two user interfaces with which you can work
to extend the capabilities of IBM Cloud Orchestrator - Process Center and Process
Designer. You can switch between them to use different functions of the product.
Process Center is a web-based application that you launch from the IBM Cloud
Orchestrator user interface. In this application, you can review and manage process
applications and toolkits that are known to the process server.
Process Designer is a stand-alone application that you install manually on a local
computer. It includes a Process Center view that provides access to the repository
but is enhanced with an Open in Designer option, with which you can design and
configure your own workflows. You use the Process Designer graphical tool to
create custom extensions to IBM Cloud Orchestrator. Pre-built sample artifacts are
provided in Business Process Manager to make process creation quick and easy.
For detailed information about IBM Business Process Manager, see the knowledge
center at http://www.ibm.com/support/knowledgecenter/SSFTDH_8.5.0/
com.ibm.wbpm.main.doc/ic-homepage-bpm.html.

296

IBM Cloud Orchestrator 2.4.0.2: User's Guide

For more information about developing process applications and toolkits, see
Developing IBM Cloud Orchestrator content.

Setting up IBM Process Designer

Install, configure, and log in to IBM Process Designer.

About this task

IBM Process Designer is a stand-alone, local application that you install on a
Windows operating system computer.

Procedure
1. In a web browser, log on to the Business Process Manager user interface as user
admin and with the password set for admin during installation.
2. Install Process Designer on a Windows machine on which you design the
workflows:
a. On the right-side panel of Process Center, click Download Process
Designer. This is a link to the Process Designer installation package.
b. Install the package as described in Installing IBM Process Designer in the
Business Process Manager information center.
3. Click Start > IBM Process Designer Edition > Process Designer and log on as
user admin with password passw0rd.

Results
Process Designer stand-alone application opens and a list of process applications is
displayed in the Process Apps tab. When you click the process application name,
you can view its details, such as snapshots, history, you can edit some details such
as name, or who can access it, but you are not able to configure the process
application in this view. To configure a process application, click Open in Designer
next to the item name.
You can switch between Designer, Inspector, and Optimizer tabs.
v To plan and design processes, use the Designer view.
v To test and debug processes, use the Inspector view.
v To analyze and optimize processes, use the Optimizer view.
To return to Process Center view, click Process Center in the upper right corner of
the screen. In the Process Center view, click Open in Designer to get back to the
Designer view.

Adding users to IBM Process Designer

If you want a new IBM Cloud Orchestrator user to be able to use Process Designer,
you must grant it access to the Process Center repository.

Procedure
1.
2.
3.
4.

Open Business Process Manager Process Designer or Process Center.

Go to Admin > Manage Users.
Click Add Users/Groups on the right side of the panel. A dialog box opens.
In the Search for Name box, enter the user name.

5. Select your user in the Results box and click Add selected.

Chapter 4. Managing orchestration workflows

297

Creating a process application in Process Designer

Create a process application and search through artifacts.

About this task

Process applications are containers in the Process Center repository for process
artifacts such as process models and supporting implementations that are created
in Process Designer.
Toolkits are collections of process assets that can be shared and reused across
multiple projects in Process Designer.
Toolkits enable Process Designer users to share library items across process
applications. Process applications can share library items from one or more toolkits,
and toolkits can share library items from other toolkits.
IBM Cloud Orchestrator provides a toolkit that is called SCOrchestrator_Toolkit. It
provides basic capabilities with which you can design orchestration processes. Any
process application that contains processes for use with IBM Cloud Orchestrator
must depend on this toolkit.
When you create a dependency on a toolkit, you can use the library items from
that toolkit for the implementation of the process steps you are building in your
current project. For example, after you create a dependency on a toolkit that
includes several services, the Designer view automatically makes those services
available when a developer is choosing the implementation for an activity.

Procedure
1. Open the Process Designer and log on with administrative credentials. The
Process Center panel is displayed. In this panel, you can review and manage
process applications and toolkits that are known to the process server.
2. Create a process application:
a. Click the Process Apps tab and in the panel on the right side, click Create
New Process App.
b. In the window that is displayed, provide a name and a unique acronym for
your new process application. Optionally, provide a description.
Remember: After the process application is created, do not change its
acronym, because it is used to reference the processes in self-service
offerings.
c. Click Create.
Tip: Steps from a to c can be performed in both Process Designer and Process
Center, with the same result, but only in Process Designer view you can
configure the process application when it is created.
3. Click Open in Designer for your newly created process application. The
Designer view is opened.
4. In the Designer view, click one of the categories from the pane on the left. A list
of artifacts that are relevant for this category is displayed. In this pane, you can
also review the existing artifacts and add new artifacts to toolkits or process
applications.
Note: You can click All in the newly created process application to see that it
initially contains only one artifact.

298

IBM Cloud Orchestrator 2.4.0.2: User's Guide

5. Create a dependency on SCOrchestrator_Toolkit:

a. Make sure the process application for which you are creating a toolkit
dependency is open in the Designer view.
b. Click the plus sign next to Toolkits in the library.
c. From the Add Dependency window, click to select SCOrchestrator_Toolkit.
6. Click TOOLKITS > System Data from the list to open the toolkit. It is one of
the default toolkits. Click All and then choose Tag, Type, or Name from the list
on the right to sort the artifacts by tag, type, or name.
7. Click the arrow in the upper right corner to toggle between expanding all
groups or expanding only one group.
Tip: You can type any set of characters on the keyboard to search for artifacts
that contain these characters.

Reusing processes and human services in a process application

After you create a process application, you can create processes and human
services within this process application. You can also use the items that already
exist in other process applications or toolkits.

About this task

In this task an example of the process application created in Creating a process
application in Process Designer on page 298 is used.
Note: The GetOperationContext activity that is delivered with the
SCOrchestrator_toolkit is required as the first activity of the human service to
integrate with IBM Cloud Orchestrator correctly. For information about
SCOrchestrator_toolkit, see SCOrchestrator toolkit .

Procedure
1. In the Process Designer view search for SCOrchestrator_Toolkit.
2. On the right side of the toolkit name, click Open in Designer. Details for the
toolkit are displayed.
3. From the list of available items on the navigation pane on the left, in the User
Interface section, right-click the Template_HumanService. That is the user
interface that you want to copy into your process application. The contextual
menu for the selected item opens.
4. In the contextual menu, click Copy Item to > Other Process App. Select your
process application from the list. The process is copied in the background. No
confirmation is provided.
Repeat steps 3. and 4. for all the items that you want to copy.
5. To return to the list of process applications and toolkits, click Process Center in
the upper right corner of the screen.

Results
When you open your process application, the Template_HumanService is now
available on the list.

Chapter 4. Managing orchestration workflows

299

Editing process applications and toolkits

You must be the author of a process application or a toolkit, if you want to edit
them.
Table 38. Editing process applications and toolkits
Action

Authorization required

Editing imported toolkits

admin

Editing current Business Process Manager

system toolkits

tw_admins, tw_authors

Creating a new process application and

referencing SCOrchestrator_toolkit as a
dependency

admin

Opening sample applications as admin

tw_admins group added to the Process

Center (open Manage Access to Process
Library)

Creating a process
Create a process using IBM Process Designer and incorporate a new activity into it.

About this task

In this example, create a sample process called "Hello World". You can modify this
procedure to suit your needs.

Procedure
1. In the Designer view, click the newly created process application and then
click the plus sign next to Processes to open the Create new menu.
2. From the menu, select Business Process Definition.
3. Provide a name for the new business process definition, for example Hello
World. Click Finish. The new process definition opens in the main canvas.
Initially, the diagram view contains two lanes:
v The System lane that is the default lane for system activities.
v The Participant lane that is the default lane for user services.
The start event and the end event are added automatically.
4. To add a user activity to the process, select Activity from the palette to the
right. Add the activity to the Participant lane. An activity represents one step
in the process. Properties of an activity are shown in the bottom panel.
5. In the Properties panel at the bottom of the screen, you can set the name of
the activity, for example Say Hello.
6. To make the activity part of a flow, connect it with the start and end event.
Select Sequence Flow from the palette.
7. With the Sequence Flow tool, click the connection points of the elements.
First, connect the start event with the activity and then connect the activity
with the end event.
8. To create an implementation for this process, click the plus sign next to User
Interface in the Designer view.
9. From the menu that opens, select Human Service and name it Say Hello. The
main canvas opens. You can now use the Coach element to create a simple
user interface dialog that brings up the Hello World string..

300

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: The checkered background indicates that an implementation is being

designed. It also indicates that there are now some elements in the palette that
were not available in the process definition step.
10. Drag the Coach element onto the canvas. Specify its name, for example Say
Hello, and double-click the element. The Coaches tab opens.
11. Drag the Output text element onto the canvas. In the Properties panel at the
bottom of the screen, change the label to Hello World.
12. Drag the Button element and change its label to OK.
13. Click Diagram to open the Diagram tab. Use the Sequence Flow tool to
connect the start event with the Say Hello step. Then, connect the Say Hello
step with the end event.
Note: Notice the OK label of the connection between the Say Hello step and
the end event. It indicates that the OK button is used to trigger the transition
to the end event.
14. Click Save to save the new human service.
15. From the list at the top, select Hello World to switch back to the previously
created process definition.
16. Click the Say Hello step. In the Properties tab at the bottom, click
Implementation and click Select.
17. From the list, choose the Say Hello human service that you created. Save the
process definition.
Note: Notice that the implementation has changed to Say Hello.
18. Click Run Process in the upper right corner. The view automatically switches
to the Inspector view. Notice that there is one active Hello World process
instance. The Diagram view at the bottom shows that the instance is at step 2
and that there is a task that is waiting to be performed.
19. Click Run the selected task in the upper right corner to run the task. The Pick
User From Role window opens. Select administrative user to run the task.
Note: The selection of users in this window is based on the Participant
Group setting of the Participant lane.
A browser window opens that shows the simple user interface that you have
defined. Such user interface is called a coach.
20. In the user interface, click OK and close the browser.
21. In the Inspector view, click Refresh. Notice that the Say Hello task is closed
and the Hello World process instance is completed.

User input required at service request time

You can configure processes which require manual input from the user.
When manual input is required for a request to complete, the user gets a task
assignment in the INBOX tab in IBM Cloud Orchestrator. You must claim the task
by clicking Claim, before you can work with the task. If the task was already
claimed by another user, the Taken status is displayed. There are two types of
tasks:
Approval requests
To approve or reject a selected request, click Accept or Reject accordingly.
Optionally, you can provide a comment in the Reason field.
General tasks
These are all tasks that are not of the approval type. Such tasks include a
Chapter 4. Managing orchestration workflows

301

Business Process Manager human service. When you select the task from
the list, the Business Process Manager coach opens. Provide any required
parameters and click Submit.

Making a new process available as a self-service offering

You can make a process that you created available as a self-service offering in IBM
Cloud Orchestrator.

Procedure
1. In Business Process Manager, expose the process to make it available in the
IBM Cloud Orchestrator user interface:
a. Open IBM Process Designer.
b. Select your process and switch to the Overview tab.
c. In the Exposing section, click Select in the Expose to start row.
d. Select the All Users participant group or any other group that you want to
expose the process to, and save the setting.
Tip: A similar procedure must be performed to make a user interface (human
service) visible in IBM Cloud Orchestrator:
a. In Process Designer, select the human service and open the Overview tab.
b. In the Exposing section, click Select in the Expose to row.
c. Select the All Users participant group or any other group that you want to
expose the process to, and save the setting.
d. In the Expose as row, click Select.
e. Select URL and save the setting.
2. In IBM Cloud Orchestrator, create an offering that is based on the process, and
a category for it. For information about creating self-service categories and
offerings, see Creating a category on page 327 and Creating an offering on
page 326.

Results
The user can now access the offering in the Self-Service Catalog, and can request
the offering.

Making a process available as an orchestration action

You can create a process in Business Process Manager and then use it as an
orchestration action for virtual system patterns (classic).

About this task

There are two types of orchestration actions:
Event-triggered actions are business processes that are triggered by a specified event
during a predefined management action. They may include a human service to
gather additional parameters that are required to complete the automation. These
actions are related to provisioning and deprovisioning.
User actions are triggered manually by a user in the Virtual System Instances
(Classic) view after the pattern is deployed. User actions are, for example, resetting
server password or backing up a server. They may include a human service.

302

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. In Business Process Manager, expose the process to make it available in the
IBM Cloud Orchestrator user interface:
a. Open IBM Process Designer.
b. Select the process and switch to the Overview tab.
c. In the Exposing section, click Select in the Expose to start row.
d. Select the All Users participant group or any other group that you want to
expose the process to, and save the setting.
The process is now visible in IBM Cloud Orchestrator.
Tip: A similar procedure must be performed to make a user interface (human
service) visible in IBM Cloud Orchestrator:
a. In Process Designer, select the human service and open the Overview tab.
b. In the Exposing section, click Select in the Expose to row.
c. Select the All Users participant group or any other group that you want to
expose the process to, and save the setting.
d. In the Expose as row, click Select.
e. Select URL and save the setting.
2. In IBM Cloud Orchestrator, create an orchestration action based on the process:
a. Log on to IBM Cloud Orchestrator. You must be assigned the catalogeditor
role or the admin role.
b. Click CONFIGURATION > Actions Registry.
c. In the actions menu, click Create Action. A new dialog opens.
d. Provide a name and, optionally, a description for the action.
e. From the Action type list, select User.
f. Select one or more virtual system patterns to which the action is applied.
g. Select the process that you exposed in step 1.
h. If the selected process requires user interaction, specify a user interface by
selecting the related Human Service.
i. Specify sequence priority if you want a specific run order to be applied. For
actions that have the same event and priority defined, the order is
unspecified.
j. Click Configure Access Control to create the action.
k. To allow other users to access the new action, select the action and add the
project to which the users belong to the Access granted to field.

Results
The action is now configured. If it is an event-triggered action, it is started
automatically for selected virtual system patterns at the time the selected event
takes place. You can now start the user action in the Virtual System Instances
(Classic) view that you can open by clicking PATTERNS > Instances > Virtual
System Instances (Classic). If user interaction is required for the configured action
to complete, the user receives a new assignment in the INBOX tab.

Chapter 4. Managing orchestration workflows

303

Upgrading a process on a development system or production

system
IBM Cloud Orchestrator enables you to distinguish between development mode
and production mode. You can define different upgrade methods for a process,
depending on whether IBM Cloud Orchestrator is configured as a development
system or as a production system.

About this task

Development mode
When IBM Cloud Orchestrator is configured in development mode, the engine
always calls the most recent version of process code.
In IBM Process Designer, the most recent version of process code is called Current
or TIP. Development mode is especially convenient during the development of
processes, because it is not necessary to create snapshots for each code change to
be tested. Instead, the already running process instances (also known as inflight
process instances) use the new modified code for the remaining part of the flow.
Development mode is configured by default after installation. For details of how to
configure development mode, see Configuring development mode on page 305.
Production mode
When IBM Cloud Orchestrator is configured as a production system, the engine
uses a snapshot version of the toolkit or process application code instead of the
latest version of code.
A Business Process Manager process must be called by a dedicated snapshot id, so
that any running process continues to use that code version, even if a new
snapshot is imported into the production system while the process is running.
The snapshot version used in production mode is determined as follows:
Toolkits
A production system uses the most recent snapshot (of the toolkit) that is
available at the start time of a process instance.
Process applications
In general, a production system uses the most recent snapshot (of the
process application) that is available at the start time of a process instance.
However, an administrator can specify a default version of a process
application. If a default snapshot is configured, the production system uses
the default snapshot instead of the most recent snapshot.
For details of how to configure production mode, see Configuring production
mode on page 305.

304

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Configuring development mode

Development mode is configured by default after installation. You do not need to
explicitly configure a system in development mode unless you are changing a
production system to a development system.

About this task

To change IBM Cloud Orchestrator from a production system to a development
system, complete the following steps:

Procedure
1. Log on to the Business Process Manager WebSphere Application Server console
as an administrator user:
https://$central-server-2:9043/ibm/console/logon.jsp

where $central-server-2 is the IP address of the server where Business

Process Manager is installed.
2. In the console navigation tree, click Servers > Server Types > WebSphere
application servers > server_name > Process definition > Java Virtual
Machine > Custom properties.
3. Select the ORCHESTRATOR_DEVELOPMENT_MODE variable.
4. To specify development mode, set the value of the
ORCHESTRATOR_DEVELOPMENT_MODE variable to true.
5. Set the description of the ORCHESTRATOR_DEVELOPMENT_MODE variable to Activate
Development Mode.
6. Restart the Business Process Manager server.

Results
IBM Cloud Orchestrator is now configured as a development system.

Configuring production mode

To configure production mode, IBM Cloud Orchestrator must be manually
configured to use a snapshot instead of the latest version of code.

About this task

To configure IBM Cloud Orchestrator as a production system, create a property in
Business Process Manager to define the operational mode, as follows:

Procedure
1. Log on to the Business Process Manager WebSphere Application Server console
as an administrator user:
https://$central-server-2:9043/ibm/console/logon.jsp

where $central-server-2 is the IP address of the server where Business

Process Manager is installed.
2. In the console navigation tree, click Servers > Server Types > WebSphere
application servers > server_name.
3. In the Java and Process Management category in the Server Infrastructure
section, click Process definition > Java Virtual Machine > Custom properties.
4. Click New to create a new variable called ORCHESTRATOR_DEVELOPMENT_MODE.

Chapter 4. Managing orchestration workflows

305

5. To specify production mode, set the value of the

ORCHESTRATOR_DEVELOPMENT_MODE variable to false.
6. Set the description of the ORCHESTRATOR_DEVELOPMENT_MODE variable to Activate
Production Mode.
7. Restart the Business Process Manager server.
Optional: To specify a default snapshot for a process application, complete the
following steps:
8. Activate the process application snapshot, as follows:
a. Open the IBM Process Designer.
b. Click the Process Apps tab.
c. Select the process application.
d. On the Snapshots page, expand the target snapshot, and then select
Activate.
9. Specify the default process application snapshot, as follows:
a. In a web browser, open the Process Admin Console.
b. Click the Installed Apps tab.
c. Select the process application.
d. In the right pane, click Make Default Version.

Results
IBM Cloud Orchestrator is now configured as a production system.

Guidelines for working with Business Process Manager

When you create toolkits or process applications, there are some best practices to
be followed in naming conventions, structuring, modeling, and error handling.

Guidelines for naming and documenting your toolkit or process

application
When you create toolkits, use the following naming conventions:
v Name the toolkit after the utility or services it provides.
v Add words like "Toolkit" or "Framework" so that you can differentiate it from
other process applications.
v Avoid long names. You must use fewer than 64 characters.
v White spaces between words can be added if it improves readability.
v Avoid the version number in the name, unless you want to bring attention to the
major changes in the solution.
v Add more information about the toolkit in Description field.
v Choose an acronym for your toolkit. Do not use the prefix "IC as it is used for
content delivered by IBM.
v Name your snapshots according to this scheme: AABB_YYYYMMDD. Exported
TWX archives of your toolkit get this snapshot name appended, so you can
easily identify the exported snapshots later.

306

AA

The IBM Cloud Orchestrator release that is prerequisite for the toolkit or
process application, for example, 24 for IBM Cloud Orchestrator V2.4.

BB

Counting up the version of the toolkit, for example. 00 for the first
release, and 01 for the second release

IBM Cloud Orchestrator 2.4.0.2: User's Guide

YYYYMMDD
The date the snapshot was created
v When updating an existing process application or toolkit, do not change the
chosen acronym because it is used to reference the processes in self-service
offerings.

Guidelines for creating artifacts in a toolkit

The general best practices are as follows:
v In the documentation field for a Business Process Manager artifact, enter a
description of the input and output parameters of that artifact.
v Use the note object of Business Process Manager to improve the readability of
complex processes and human services.
v As mentioned in the naming conventions, provide an understandable and
meaningful name for your artifacts.
v Keep the interface definition between a Business Process Manager Human
Service and its associated Business Process Manager Business Process Definition
as short as possible. The interface is defined by a Business Process Manager
Business Object. This object is used to correlate a business process with its
associated human services in the IBM Cloud Orchestrator UI. Use the Business
Process Manager human service only to collect the parameters that are needed
by its associated business process. Implement the business logic in the business
process. It also helps if you enable the business process to be called by using the
REST API from an external application, such as a portal application.
v Avoid Pre and Post execution assignments. Instead, add explicit activities, if
needed. The execution assignments are hidden in the Business Process Manager
Process Designer, and the logic of the corresponding activity or service becomes
difficult to understand. If needed, use the Pre and Post executions to make
simple assignments like initializing the associated Business Process Manager
artifact. For example, consider having two consecutive coaches in a human
service. In such cases, do not initialize the objects that are used by the second
coach as being Post execution assignment of the first coach. If needed, do the
initialization as a pre-execution assignment of the second coach.
v Do not use passwords in environment variables or other artifacts that are visible
to everyone.
v When you deliver a solution for IBM Cloud Orchestrator, make sure that there
are no validation errors. These errors can be seen in the Process Designer.
v Avoid changing the interface of a building block that is delivered as a part of a
toolkit. If you change the interface of building blocks in a toolkit, it becomes
cumbersome for all its dependent toolkits or Process Applications. Even
changing the name might lead to redoing the mapping for all activities or
services that use the building block.

Guidelines to structure your solution

v In general, an extension content solution for IBM Cloud Orchestrator consists of
a Business Process Manager Process Application and a Business Process Manager
Toolkit.
The basic rule is that a process application contains artifacts that are ready to be
used by the user and not meant to be changed or adapted to be useful. All other
artifacts are better placed in a toolkit.
v When structuring your solution, always consider the visibility of your artifacts.
Artifacts of one process application are not visible by default to another process
application.
Chapter 4. Managing orchestration workflows

307

For example, a Business Process Manager, process A, can be called by another

Business Process Manager, process B. The Linked Process activity is used if
both are in the same process application or if process A is in a dependant toolkit.
Avoid cyclic dependencies, that is, when toolkit A depends on toolkit B, avoid
having a dependency on toolkit A. If such a cyclic dependency occurs,
restructure your toolkits to resolve it.
v Use Business Process Manager tags and smart folders to structure your solution
to make it more understandable. If you have UI parts that can be used in UI
panels, define them as Coach views. These views can be reused in different
Coaches. If you must change something later, for example, wording, you change
only the reusable Coach view.

Guidelines for handling errors

An IBM developerWorks article explains extensively about exception handling and
logging from a business process management perspective. See Related Links. It
identifies the types of exceptions that are encountered in a Business Process
Manager scenario. Also, it shows you how to handle them using IBM Business
Process Manager.
The following are best practices in error handling:
v Use the PostMessage integration service that is delivered as a part of the
SCOrchestrator_Toolkit to report messages that occur in Business Process
Manager processes or Human Services back to the IBM Cloud Orchestrator UI.
For event and instance operations, these messages are written to the history
section of the pattern instance. For self-service offerings, these messages are
written to the operationContext and are displayed in the UI.
v Define error message as localization resources.
v Raise errors in your integration services or processes using the Error End Event
node.
v Catch raised errors raised from integration services using Intermediate Error
Events or Event Subprocesses.
v For Java classes that are used in Business Process Manager processes or human
services, define logging framework. For example, java.util.logging to log
messages to the WebSphere log.
v Use the logging capabilities of Business Process Manager to log messages to the
WebSphere log. A good practice is to log in the entry and exit of an activity to
support debugging better.
Related information:
http://www.scribd.com/doc/92505753/IBM-Impact-2011-Five-Guidelines-toBetter-Process-Modeling-for-Execution-Stuart-and-Zahn
You can find many documents with guidelines and best practices about business
process modeling. One of it is Five Guidelines to Better Business Process Modeling for
Execution from Jonas A. Zahn and Stuart Jones, which describes the following design
guidelines:
Rule of Seven - limit any view to no more than seven steps for a good fit.
Activity granularity - activities must be similar in scope at each level. Avoid the
String of Pearls pattern, that is, series of activities in the same lane.
Activity description - use [action verb] + [business object] and avoid vague
verbs like process and perform.
http://www.ibm.com/developerworks/websphere/library/techarticles/
1105_ragava/1105_ragava.html

308

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 5. Working with self-service

IBM Cloud Orchestrator provides an intuitive Self-service user interface, where you
can use the Self-Service Catalog to request resources. For example, you can deploy
virtual machines, add volumes, or manage key pairs. From this interface, you can
also monitor your requests and manage your resources.

About this task

IBM Cloud Orchestrator provides a rich set of predefined offerings in the
Self-Service Catalog. In addition, Service Designer can create offerings with IBM
Process Designer, and populate the Self-Service Catalog with additional offerings.
An offering is a Business Process Manager process in the Self-Service Catalog. For
information about toolkits that you can use to build offerings, see Developing IBM
Cloud Orchestrator content.

Using self-service
Use the IBM Cloud Orchestrator Self-service user interface to request resources,
monitor the status of your requests, and do additional tasks related to resources.

Viewing the dashboard

Use the DASHBOARD tab to monitor tasks, requests, quota usage, and virtual
machine status for the current project.

Inbox
The Inbox area provides an overview of the inbox statistics.
The section header displays the number of each of the following types of tasks:
v New today
v To-do (tasks that have not yet been claimed)
v Overdue
The table displays the following information about the most recent tasks:
v Latest Items
v Requested by
v Priority
v If a task is overdue, the overdue icon is displayed.
Click a task type in the section header, or click an item in the table, to open the
INBOX tab.

Request History
The Request History area provides an overview of requests statistics.
The section header displays the number of each of the following types of requests:
v New today
Copyright IBM Corp. 2013, 2015

309

v In progress
v Failed
The table displays the following information about the most recent requests:
v Latest Requests
v Submitted On
v Status
Click a request type in the section header, or click an item in the table, to open the
REQUEST HISTORY tab. If you click a request type, only requests of that type are
displayed.

Quota Usage of Current Project

The Quota Usage of Current Project area provides the current aggregate of the
following items for the current project:
v vCPU Usage
v RAM (MB) Usage
v Volume (GB) Usage
Aggregates are based on all virtual machines in your project across all regions.
Usage is displayed as a percentage. The dial displays 50%, 75%, and 100%
threshold indicators, which are color-coded as follows:
Table 39.
Color

% Usage

Green

0-50

Yellow

51-75

Red

76-100

VM Status
The VM Status area provides information about the deployed virtual machines for
the current project. The total number of deployed virtual machines in your project
across all regions is displayed, with a breakdown based on status. The virtual
machine status is color-coded as follows:
Table 40.
Color

Status

Green

Active

Blue

Paused

Red

Error

Yellow

Shutoff

Click a status type to open the ASSIGNED RESOURCES tab. The tab contents are
filtered to display only virtual machines with the selected status.

310

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Submitting a self-service request

Use the SELF-SERVICE CATALOG tab to view the list of offerings and submit a
self-service request.

Procedure
1. Log on to the IBM Cloud Orchestrator Self-service user interface and click the
SELF-SERVICE CATALOG tab.
2. Open the category of your choice to view the offerings. You can also use the
Search field to look up a specific offering by name.
3. Select an offering from the list. A window with request details opens.
4. Specify any required parameters for the request.
5. Click OK to submit the request.

Results
The request is submitted. A message is displayed at the top of the page, reporting
the result. You can also check the request status in the REQUEST HISTORY tab.

Viewing the status of your requests

Use the REQUEST HISTORY tab to review the status of your requests.

About this task

Users can view the progress of all the requests that they submitted from the
Self-Service Catalog. Administrators can also view all the requests submitted by the
users that they administer. Completed requests are automatically removed from the
view after two weeks.

Procedure
1. Click the REQUEST HISTORY tab. All the requests that you have access to are
displayed on the left side of the page.
You can search for a specific request and sort the requests in the view.
2. Click any request to view its details.

Managing resources
Use the ASSIGNED RESOURCES tab to manage your assigned resources.
The columns for each instance type table can vary. From the table view you can
launch actions on a single instance or on multiple instances. To view detailed
information about an instance click anywhere on the instance row. The details
screen contains actions that pertain only to the selected instances.

Resource types
IBM Cloud Orchestrator supports several types of resources, including domains,
virtual machines, and volumes. Resources types are also known as instance types
(for example, in the Core Services REST API).
IBM Cloud Orchestrator provides the following resource types:
Action
An action is an instance that can be applied to other instances. An action
always includes a Business Process Manager process that can be run on the
associated instance.
Chapter 5. Working with self-service

311

Category
A category is a container for self-service offerings that are displayed in the
Self-Service Catalog. You can organize your offerings inside the catalog.
Domain
A domain is the highest entity in the identity model. It is a container and
namespace for projects and users of a customer.
Heat

The Heat instance type represents a combined set of virtual machines

created via a Heat template in OpenStack.

Offering
An offering is an IBM Cloud Orchestrator process made available in the
Self-Service Catalog. IBM Cloud Orchestrator provides a set of offerings
out of the box. However, you can create your own offerings with IBM
Process Designer.
Openstackvms
An instance of type openstackvms represents a single OpenStack virtual
server.
Project
A project is a container that owns resources such as virtual machines,
stacks, and images.
User

A user represents the account of a person. You can log in to IBM Cloud
Orchestrator with a user account. A user must always be member of at
least one project.

Volumes
The volumes instance type is the disk space resource that can be attached
to a virtual server.

Working with resources

You can work with your assigned resources from the ASSIGNED RESOURCES
tab in the navigation menu.
You can search for a particular resource by selecting the resource type and
specifying the resource name, description, or status in the search field. The
resource table can be sorted using any column that has the sort icon.
Applying an action to a resource:
Use the ASSIGNED RESOURCES tab to select an action for a particular instance,
for example, to start or stop a virtual machine.
Procedure
1. Log in to the Self-service user interface and click ASSIGNED RESOURCES.
2. Select an instance by selecting the single row check box. Select multiple
instances by selecting the check box in the header row.
3. Select the action that you want to execute from the Actions box on the left. The
following options are displayed based on the action type selected:
Human service
If the action you select requires a human service, a window with
request details opens. Specify any required parameters for the request.
Click OK to execute the action or Cancel to return to the previous
view.

312

IBM Cloud Orchestrator 2.4.0.2: User's Guide

No human service
If the action you select does not require a human service, a
confirmation dialog box is displayed. Select Continue to execute the
action or Cancel to close the dialog and return to the main view.
Note: When an action is executed, a message is displayed at the top of the
page, reporting the result. You can also check the request status in the
REQUEST HISTORY tab.
Related concepts:
Managing actions on page 327
A Service Designer can manage actions and their access control list in the Actions
Registry.
Removing from the list of managed servers in PowerVC:
PowerVC treats base instances used for the capture of images no differently from
other servers on the system. This means there is the possibility for the base servers
to be deleted accidentally by administrators. To avoid this, it is recommended that
after a server is captured as an image, it should be removed from PowerVC.
Removing a server does not affect the server except it is no longer managed by
PowerVC and it cannot be deleted inadvertently.
About this task
Removing a server does not affect the server or its associated disk. If needed, the
server can be managed through the servers panel.
Procedure
1. Click on the Hosts icon in the side panel on the left of the screen.
2. Click on a specific Host. A panel appears displaying a list of managed servers
on that host.
3. Select the server you want to remove and click Remove in the menu bar.
4. A window appears asking you to confirm removing the virtual machine you
have selected from PowerVC management. Click OK.
Results
The server has been removed and can no longer be managed by PowerVC.

Managing virtual machines

The IBM Cloud Orchestrator Self-Service Catalog provides self-service offerings to
deploy virtual machines using the OpenStack Nova component. It can also register
and unregister a public and private key pair that can be used to access the virtual
machine.

Chapter 5. Working with self-service

313

Deploying a virtual machine:

The IBM Cloud Orchestrator Self-Service Catalog provides a default offering that
you can use to deploy a single virtual server using OpenStack Nova.
Before you begin
v Resources such as images, flavors, keys, and networks, must be defined in the
OpenStack environment. Otherwise, the virtual machine cannot be deployed.
v Images must be stored within OpenStack Glance.
v Flavors and networks must be defined in OpenStack.
v Keys must be registered with a project.
v For tasks such as processing user data or metadata, the image must be prepared
to include the cloud-init package.
v Assign the region and availability zone to the project.
Note: AIX images do not have the ability to change the password of a user or
inject a SSH key at deploy time. Though these options do not work for AIX, they
are available on the page.
Procedure
1. Log in to the Self-service user interface as an End User.
2. In the menu bar, click SELF-SERVICE CATALOG.
3. Click Deploy cloud services > Deploy a single virtual server. The Deploy a
single virtual server page opens.
4. Select the region where the virtual server should be deployed to.
5. Click Next.
6. Enter the virtual server details:
a. Specify a Server Name.
b. Select an image, availability zone and flavor from the drop down menus.
Select the network by selecting the check box beside the network name.
For more information about availability zones, see:
v Assigning a zone to a domain
v Modify the availability zones of a project
c. Optional: Select Use Key to Access Virtual Machine and, in the displayed
menu, select one of the keys to access a virtual machine.
d. Optional: Select Set UserId and Password. Enter a user ID and specify
whether a password must be set on the virtual machine. To set the
password on the virtual machine, the cloud-init package must be installed
on the deployed image. Another check box is displayed to specify whether
the password must be changed at the first login.
The default user to be used can be configured in the cloud-init
configuration file. Each Linux distribution has its own default user. For
more information, see http://cloudinit.readthedocs.org/en/latest/topics/
examples.html.
Note: For Microsoft Windows virtual machines: Do not edit the UserId
field. You can change the password only for the user who is specified in the
cloudbase-init configuration file.
e. Optional: Click Attach Volume and in the displayed window select the
volumes to be attached to the deployed virtual machine.

314

IBM Cloud Orchestrator 2.4.0.2: User's Guide

What to do next
Proceed to Managing virtual machine instances.
Managing virtual machine instances:
Virtual machine instances represent the servers (virtual machines) that are running
in the OpenStack backend of IBM Cloud Orchestrator.
IBM Cloud Orchestrator provides a built-in instance type called OpenStack virtual
machines which provide the functionality to manage deployed virtual machines.
To
1.
2.
3.

work with virtual machines, complete the following steps:

Log in to the Self-service user interface as an End User.
Click ASSIGNED RESOURCES.
Click Virtual Machines to display a table of virtual machines.

4. From the region list, select a region. The table shows only the virtual machines
in the specified region.
From this view, you can perform the following actions:
Starting one or more virtual machines
1. In the table, select one or more virtual machines that have the SHUTOFF
status.
2. In the Actions menu to the left of the table, click Start.
Note: This action is available only if all of the selected virtual machines
have the SHUTOFF status.
Stopping one or more virtual machines
1. In the table, select one or more virtual machines that have the ACTIVE
status.
2. In the Actions menu to the left of the table, click Stop.
Note: This action is available only if all of the selected virtual machines
have the ACTIVE status.
Note: If the virtual machine was deployed with a virtual system
pattern and you stop it from this panel, the virtual machine is
automatically restarted by the Workload Deployer component. To stop
a virtual machine deployed with a virtual system pattern, perform the
action from the PATTERNS > Instances > Virtual System Instances
panel.
Deleting one or more virtual machines
1. In the table, select one or more virtual machines that have the ACTIVE
status.
2. In the Actions menu to the left of the table, click Delete.
Note: This action is available only if all of the selected virtual machines
have the ACTIVE status.
Resizing a virtual machine
1. In the table, select a single virtual machine.

Chapter 5. Working with self-service

315

2. In the Actions menu to the left of the table, click Resize to change the
flavor of an existing virtual machine. You can see the current flavor of
the virtual machine, and select the desired flavor.
Tip: After a resize action to increase the disk size of the virtual
machine successfully completes, the disk is increased from a hypervisor
point of view. If you log on to the virtual machine and the file system
does not reflect the new disk size, you must rescan or reboot to reflect
the changed disk size. This action depends on the operating system and
disk type, as follows:
v Microsoft Windows: For information about how to resize the file
system without a reboot, see the Microsoft TechNet article Update
disk information.
v Linux: For information about how to adapt a file system after you
increase the virtual disk, see the VMware Knowledge Base article
Increasing the size of a disk partition (1004071) .
Executing a script
1. In the table, select one or more virtual machines that have the ACTIVE
status and also have a key pair defined.
2. In the Actions menu to the left of the table, click Execute Script.
3. From the Select network list, select the network interface to be used for
the script execution. Click OK.
4. Specify the following script parameters:
v Script Repository path.
v The Script Repository SubFolder specifies a subfolder under the
Script Repository where the script is located. If blank, the Script
Repository path is used.
v Script Name.
v SSH User.
v Destination Directory.
v Working Directory.
v Command Line.
Note: The Execute Script action is implemented using the
SCOrchetrator_Scripting_Utilities Toolkits.
Note: This action is only available if the ssh-key is used to access
the virtual machine which is specified during deployment.
5. Click OK.
Note: When deploying instances to a VMware region, the name specified at
deployment time is propagated from the Self-service user interface to the
OpenStack component. The instance is created in the VMware hypervisor using the
corresponding OpenStack UUID. To match an instance in OpenStack with the
actual instance deployed on VMware, complete the following steps:
1. On the Region Server where the deployment occurred, run the nova list
command and identify the instance UUID in the command output.
2. In the vCenter client, in the search field, type the instance UUID and press
Enter.
Related tasks:

316

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Applying an action to a resource on page 312

Use the ASSIGNED RESOURCES tab to select an action for a particular instance,
for example, to start or stop a virtual machine.

Working with Heat templates and stacks

You can deploy Heat templates and manage the related Heat stack instances.
IBM Cloud Orchestrator supports:
v OpenStack Heat Orchestration Templates (HOT), called Heat templates.
v OpenStack Heat stacks, called Heat stacks or Stacks, that are instances of
deployed Heat templates.
Deploying a Heat template:
The IBM Cloud Orchestrator Self-Service Catalog provides a built-in offering that
you can use to deploy an OpenStack Heat template.
Before you begin
The Heat template must be a valid Heat Orchestration Template (HOT), as defined
in the OpenStack HOT specification. All resources that are referenced in the Heat
template must be defined in the OpenStack environment:
v Images must be stored in OpenStack Glance.
v Flavors and networks must be defined in OpenStack.
v Keys must be registered in a project.
For tasks like processing user data or metadata, the image must be prepared to
include the cloud-init package and the heat-cfntools package. For more
information about creating images, see Creating base images on page 332.
Note: If you want to deploy a complex Heat template (for example, templates with
WaitCondition and waithandle or templates with SoftwareDeployment resource),
perform the following steps:
1. Set the option deferred_auth_method=trusts in the configuration file of the
Heat engine (/etc/heat/heat.conf) and restart the Heat engine by running the
service openstack-heat-engine restart command.
2. Create a heat_stack_owner role in Keystone.
3. Assign the heat_stack_owner role to the user.
Note: For AIX images, you cannot change the password of a user or inject an SSH
key at deployment time.
Procedure
1. Log in to the Self-service user interface as an End User.
2. Click SELF-SERVICE CATALOG.
3. Click Deploy cloud services > Deploy a cloud service using stacks. The
Deploy a cloud service using stacks page opens.
4. Select Direct Input and paste the template text in the Enter Heat Template
field. For information about Heat template format and specification, see Heat
template examples on page 318.
5. Click Next. The Launch Heat Template page opens.
6. In the Stack Name field, specify the name of the Heat stack instance to be
deployed.
Chapter 5. Working with self-service

317

7. Specify the timeout value for the deployment. If the stack is not deployed
within the specified time, an error message is displayed.
8. Optional: If you want to roll back the Heat instance if the stack fails to deploy,
select the Rollback on failure check box.
9. If the template contains parameter definitions, each parameter name,
description, and value is listed in the Parameters table.
For each parameter, specify the parameter value:
v Default parameter values might be provided in the parameter definition in
the template.
v If a parameter description is prefixed with the name of a supported lookup
annotation, you can select the parameter value from a list in the Select
Value column.
v Otherwise, you must type the parameter value in a field in the Enter Value
column.
10. Optional: To modify the Heat stack resources, click Stack Details:
a. Select the resource that you want to modify.
b. To view details of the volumes that are attached to the selected resource,
click Volumes. To attach a volume to the selected resource, click Add
Volume, specify the volume size and mount point, and click OK.
c. To view details of the networks that are attached to the selected resource,
click Network Interfaces. To attach a network to the selected resource,
click Add Network Interface, specify the network name and fixed IP
address, and click OK.
d. To return to the Launch Heat Template page, click OK.
11. Click OK. A REST call is posted to the OpenStack Heat engine, and the Heat
template is deployed.
12. Monitor the status of your deployment request, as described in Viewing the
status of your requests on page 311.
Tip: If a problem occurs while you are deploying a Heat template, check the
following log files for detailed information:
v In the Business Process Manager server:
/opt/ibm/BPM/v8.5/profiles/Node1Profile/logs/SingleClusterMember1/SystemOut.log

v In the virtual machine where Heat is installed:

/var/log/heat/api.log
/var/log/heat/engine.log

What to do next
You can manage the deployed Heat stack. For information, see Managing Heat
stacks on page 321.
Heat template examples:
A Heat template is a valid Heat Orchestration Template (HOT), as defined in the
OpenStack HOT specification.
For detailed information about the Heat Orchestration Templates, see the
OpenStack Template Guide at http://docs.openstack.org/developer/heat/
template_guide/. In the guide, you can find the following information:
v The introduction and some basic examples at http://docs.openstack.org/
developer/heat/template_guide/hot_guide.html

318

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v The Heat Orchestration Template specification at http://docs.openstack.org/

developer/heat/template_guide/hot_spec.html
v The OpenStack Resource Types and the related parameters at
http://docs.openstack.org/developer/heat/template_guide/openstack.html
The Heat Orchestration Templates are under development, so the OpenStack
Template Guide is periodically updated by the community.
When developing a template, it is recommended to use parameters and to avoid
hardcoded values.
In the following examples, Example 1 and Example 2 are taken from the
OpenStack Template Guide and show the differences in using hardcoded values or
parameters.
Example 3 on page 320 shows how to use lookup annotation to generate a list of
possible values for a parameter, which helps the user to select a valid parameter
value. The following lookup annotations are supported:
SCOIMAGE
Lookup of images from the image repository for the region.
SCOFLAVOR
Lookup of flavor size from the selection available in the region.
SCONETWORK
Lookup of available networks in the region.
SCOKEY
Lookup of the registered keys for the project.
Note: Heat Orchestration Templates are sensitive to formatting issues. To avoid
template validation errors, use the correct indentation.
Example 1
The following example is a simple Heat template to deploy a single virtual system
and it is limited to a single combination of image, key, and flavor values that are
hardcoded in the template:
heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance with hardcoded values
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: my_key_pair_1
image: cirros-0.3.1-x86_64
flavor: m1.tiny

Example 2
The following example is a Heat template to deploy a single virtual system with
parameters and it is therefore reusable for other configurations:
heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance with parameters
parameters:
key_name:
Chapter 5. Working with self-service

319

type: string
label: Key Name
description: Name of key-pair to be used for compute instance
image_id:
type: string
label: Image ID
description: Image to be used for compute instance
instance_type:
type: string
label: Instance Type
description: Type of instance (flavor) to be used
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: { get_param: key_name }
image: { get_param: image_id }
flavor: { get_param: instance_type }

Example 3
The following example is a simple Heat template to deploy a stack with two
virtual machine instances by using lookup annotations for parameters:
heat_template_version: 2013-05-23
description: Simple template to deploy a stack with two virtual machine instances
parameters:
image_name_1:
type: string
label: Image Name
description: SCOIMAGE Specify an image name for instance1
default: cirros-0.3.1-x86_64
image_name_2:
type: string
label: Image Name
description: SCOIMAGE Specify an image name for instance2
default: cirros-0.3.1-x86_64
network_id:
type: string
label: Network ID
description: SCONETWORK Network to be used for the compute instance
resources:
my_instance1:
type: OS::Nova::Server
properties:
image: { get_param: image_name_1 }
flavor: m1.small
networks:
- network : { get_param : network_id }
my_instance2:
type: OS::Nova::Server
properties:
image: { get_param: image_name_2 }
flavor: m1.tiny
networks:
- network : { get_param : network_id }

Example 4
The following example is a simple Heat template to set the admin password for a
virtual machine by using the user_data section:

320

IBM Cloud Orchestrator 2.4.0.2: User's Guide

heat_template_version: 2013-05-23
description: Simple template to set the admin password for a virtual machine
parameters:
key_name:
type: string
label: Key Name
description: SCOKEY Name of the key pair to be used for the compute instance
image_name:
type: string
label: Image Name
description: SCOIMAGE Name of the image to be used for the compute instance
password:
type: string
label: password
description: admin password
hidden: true
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: { get_param: key_name }
admin_user: sampleuser
image: { get_param: image_name }
flavor: m1.small
user_data:
str_replace:
template: |
#!/bin/bash
echo "Setting password to " $password
echo $password |passwd --stdin sampleuser
params:
$password: { get_param: password }

Related information:
OpenStack Heat Orchestration Template (HOT) Specification
OpenStack Heat Orchestration Template (HOT) Guide
OpenStack Building JEOS images for use with Heat
Managing Heat stacks:
You can use the Self-service user interface to manage deployed Heat stacks.
Procedure
1. Log in to the Self-service user interface as an End User.
2. Click ASSIGNED RESOURCES > Stacks.
The page shows a list of deployed Heat stacks, with an Actions menu to the
left of the list.
If you select one or more Heat stacks in the list, the Actions menu is updated
to show only the actions that you can apply to the selected Heat stacks.
3. To show more details about a Heat stack, click the Heat stack name in the
instance list.
The Heat Stack Details page is displayed. The details page also displays a list
of the virtual machine instances that are associated with the Heat stack. The
Actions menu is updated to show only the actions that you can apply to the
selected Heat stack.
Chapter 5. Working with self-service

321

Related tasks:
Applying an action to a resource on page 312
Use the ASSIGNED RESOURCES tab to select an action for a particular instance,
for example, to start or stop a virtual machine.

Managing key pairs

You can use offerings in the Self-Service Catalog to manage key pairs.
Registering a key pair:
The Self-Service Catalog provides a self-service offering to register a public or
private key pair in the context of a project. The key can be used to access virtual
machines securely without using userid and password. All users of the project can
see and use this key pair.
Procedure
1. Log in to the Self-service user interface as a Cloud Administrator.
2. In the menu bar, click SELF-SERVICE CATALOG.
3. Click Deploy cloud services > Register a key to enable access to virtual
servers to enable access to virtual servers.
4. Enter a Project name, Key Name, Public Key and Private key in the fields
provided.
Note: If you click Generate Public And Private Key, a public or private key
pair is generated and displayed in the corresponding fields of the panel.
5. Click OK.
Results
A message appears indicating that a key was registered successfully.
Unregistering a key pair:
The Self-Service Catalog provides a self-service offering to unregister a public or
private key pair defined in the context of a project.
About this task
You cannot unregister a key pair if a virtual machine exists that has the key pair
defined.
Procedure
1. Log in to the Self-service user interface as a Cloud Administrator.
2. In the menu bar, click SELF-SERVICE CATALOG.
3. Click Deploy cloud services > Unregister keys.
4. Enter a name for the project.
5. A table shows all the key pairs defined in the context of the project. Select one
or multiple key pairs to be unregistered by selecting the check box beside the
key pair.
6. Click OK.

322

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Results
A message appears indicating that the key pairs you selected are now unregistered
and no longer available to be selected during provisioning of a virtual machine.

Viewing the status of actions

Use the ACTION LOG tab to review the status of your actions.

About this task

You can view the progress of all actions that you have submitted and that are
related to resources and configuration. Administrators can also view all the actions
submitted by the users that they administer.
The requests submitted from the Self-Service Catalog are not displayed in this
view. For information about viewing the status of a request, see Viewing the
status of your requests on page 311.

Procedure
1. Click the ACTION LOG tab. All the actions that you have access to are
displayed on the left side of the page.
You can search for a specific action and sort the actions in the view.
2. Click any action to view its details.

Working with patterns

Use the PATTERNS tab to manage virtual applications, virtual systems, and
shared services.
For more information about working with patterns, see Chapter 7, Managing and
deploying virtual patterns, on page 353.

Managing the Inbox

Use the INBOX tab to view and process pending tasks and approvals.

Viewing the Inbox

The Inbox lists the tasks and approvals that are currently waiting to be claimed.
To view the Inbox, complete the following steps:
1. Log in to the Self-service user interface as an End User.
2. Click the INBOX tab.
If new tasks or approvals are created, the notification number increases and is
displayed in the INBOX tab. The notifications are updated every minute. The
INBOX notifications have three common states:
v The notifications number increases when:
A user clicks Reassign Back on one or many of the tasks or approvals.
New tasks or approvals are generated. After approximately 1 minute, the
system sees these unassigned tasks and approvals and increases the
notifications number.
Note: If there are more than 100 approval requests waiting to be claimed, the
notifications number is displayed as 100+.
Chapter 5. Working with self-service

323

v The notifications number decreases when:

A user claims one or many of the tasks or approvals. After approximately 1
minute, the system sees that the tasks or approvals have been claimed and
decreases the notifications number.
v No notifications number is displayed when:
There are no tasks waiting to be claimed by the user.

Processing an Inbox assignment

When a submitted request requires any user interaction, such as an approval, or
providing additional parameters, the responsible users get an assignment in their
Inbox.

Procedure
1. Log in to the Self-service user interface and click the INBOX tab. A list of
assignments that require user interaction is displayed. There are the following
types of assignments:

Approval request

General task
v
You can click the assignment icon to see details about it.
2. The assignment can have one of the following statuses:
v If the assignment was still not claimed by any user, the Claim button is
displayed. Click Claim to take the ownership of the assignment.
v If you already claimed the assignment, the Reassign Back button is
displayed. Click Reassign Back to release the assignment and allow another
user to claim it.
3. To complete an assignment that you claimed, perform the following steps:
a. Click on the assignment icon to view the assignment details.
b. If you want to complete a general task, enter any information required and
click Submit.
c. If you want to complete an approval request, click Accept or Reject. You
can optionally enter a reason.
A completion message is displayed and the assignment is deleted from the
INBOX tab.

Designing self-service
A Service Designer can manage the artifacts in the Self-Service Catalog, and use
them to customize the IBM Cloud Orchestrator environment. A Service Designer is
a user with the catalogeditor role.
Related concepts:
Developing IBM Cloud Orchestrator content
IBM Cloud Orchestrator content is a set of automation packages to enable IBM
Cloud Orchestrator to use the features that are delivered by external software and
infrastructure devices.

324

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Self-Service Catalog default contents

IBM Cloud Orchestrator provides a set of default offerings and categories in the
Self-Service Catalog to help you to manage cloud services and deploying virtual
systems. You can modify the catalog to add, modify, and remove offerings
according to your needs.
In the Self-service user interface, click SELF-SERVICE CATALOG to view the
categories available in the Self-Service Catalog and the related description. Click a
category to view the associated offerings.

Self-Service Catalog population tool

The Self-Service Catalog population tool is used to create categories and offerings
in the catalog using an XML file as input.
For every content pack released by IBM, a specific XML file is provided. You can use
the file to automate the IBM Cloud Orchestrator catalog update to add the
categories and offerings delivered with the content pack.
To use the Self-Service Catalog population tool, run the following script that is
stored on Central Server 2 in the /opt/ibm/ccs/catalog directory:
catalogTool.sh <xml_file_name_for_the_content_pack> <cloud_admin_user> <cloud_admin_pwd>

Managing offerings
A Service Designer can managing offerings and their access control list in the
Self-Service Catalog.
In the Self-service user interface, click CONFIGURATION > Self-Service Catalog
in the navigation menu, and then click Offerings. You can search for an offering
by specifying the offering name or description in the search field. The offering
table can be sorted using any column that has the sort icon.
If you select one or more offerings in the table, the Actions menu is updated to
show only the actions that you can apply to the selected offerings.
Depending on your permissions, you can perform the following actions:
Create an offering
See Creating an offering on page 326.
Edit an offering
Select an offering in the table and click Edit Offering.
Delete a category
Select one or more offerings in the table and click Delete Offering.
Modify the access control list of an offering
See Modifying the access control list of an offering on page 326.

Chapter 5. Working with self-service

325

Creating an offering
You can create a new offering in a domain.

Procedure
Log in to the Self-service user interface as a Service Designer.
In the navigation menu, click CONFIGURATION > Self-Service Catalog.
Click Offerings in the menu below the navigation menu.
Click Create Offering in the Actions menu. The Create Offering window is
displayed.
5. Enter a name for the offering.
6. Select an icon and a category for the offering.
1.
2.
3.
4.

7. Optional: Enter a description for the offering.

8. Select a process, application and human service for the offering.
To find the process, select the application to filter the processes by that
application. After the process is found, select the user interface from the list of
available human services for the selected process. Configure the access control.
By default any user in the same domain can use the offering. The Domain
Administrator and the Service Designer in the domain are allowed to modify
the offering.
9. Click Create.

Results
A message appears indicating that the offering is created successfully.

Modifying the access control list of an offering

You can modify the access control list of an offering by adding or removing access.

Procedure
1. Log in to the Self-service user interface as a Service Designer.
2. In the navigation menu, click CONFIGURATION > Self-Service Catalog.
3. Select an offering and click Modify Access Control List in the Actions menu.
The Modify Access Control List window appears displaying the list of the
roles in the specified domain and project that have access rights to the offering.
4. You can perform the following actions:
v To create a new entry in the list, specify the a domain, a project, a role, and
select the appropriate access rights. Click Add to Access Control List.
v To remove an access control entry from the list, click the related Delete icon.
5. Click Save.

Managing categories
A Service Designer can manage categories in the Self-Service Catalog.
In the Self-service user interface, click CONFIGURATION > Self-Service Catalog
in the navigation menu, and then click Categories. You can search for a category
by specifying the category name or description in the search field. The category
table can be sorted using any column that has the sort icon.
If you select one or more categories in the table, the Actions menu is updated to
show only the actions that you can apply to the selected categories.

326

IBM Cloud Orchestrator 2.4.0.2: User's Guide

You can perform the following actions:

Create a category
See Creating a category.
Edit a category
Select a category in the table and click Edit Category.
Delete a category
Select one or more categories in the table and click Delete Category.

Creating a category
You can create a new category in a domain.

Procedure
1. Log in to the Self-service user interface as a Service Designer.
2. In the navigation menu, click CONFIGURATION > Self-Service Catalog.
3. Click Categories in the menu below the navigation menu.
4. Click Create Category in the Actions menu. The Create Category window is
displayed.
5. Enter a name for the category.
6. Select an icon for the category.
7. Enter a description for the category.
8. Click Create.

Results
A message appears indicating that the category is created successfully.

Managing actions
A Service Designer can manage actions and their access control list in the Actions
Registry.
In the Self-service user interface, click CONFIGURATION > Actions Registry in
the navigation menu to manage actions. You can search for an action by specifying
the action name or description in the search field. The action table can be sorted
using any column that has the sort icon.
To manage actions on Virtual System (Classic) Pattern instances, see User actions
on page 295.
If you select one or more actions in the table, the Actions menu is updated to
show only the actions that you can apply to the selected actions.
Depending on your permissions, you can perform the following actions:
Create an action
See Creating an action on page 328.
Edit an action
Select an action in the table and click Edit Action.
Delete an action
Select one or more actions in the table and click Delete Action.
Modify the access control list of an action
See Modifying the access control list of an action on page 329.
Chapter 5. Working with self-service

327

Creating an action
You can create a new action in a domain.

Procedure
1. Log in to the Self-service user interface as a Service Designer.
2. In the navigation menu, click CONFIGURATION > Actions Registry.
3. Click Create Action in the Actions menu. The Create Action window is
displayed.
4. Enter a name for the action.
5. Select an icon and a process for the action.
6. Optional: Enter a description for the action. Select the type of instance the
action applies to including the tags you want the action to apply to. Select an
application and human service for the action.
Note: You must specify which instance the action applies to. Based on the
selection of the type, choose from a list of tags that the instance could have.
The action only appears on instances having the type and tag. The field Specify
the item selection criteria allows you to specify whether the action is able to:
v Create an instance. Select createInstanceAction.
v Modify only a single instance. Select singleInstanceAction.
v Modify multiple instances. Choose multiInstanceAction.
Select the application to filter the processes by that application. Once the
process has been found, select the user interface from the list of available
human services for the selected process. Then, configure the access control. The
Domain Administrator and catalog editor of the domain are allowed to modify
the offering.
7.

Tags are working as an additional filter mechanism for actions to be performed

on selected instances or resources. As an example take the Start action for
virtual servers. It has the tag shutoff. This means that the Start action will
only be available for virtual servers (openstackvms) that are stopped. Those
tags can be set during action creation or modification in the Actions Registry
depending on the selected instance (resource) type (for example,
openstackvms). The following tags are provided by IBM Cloud Orchestrator
through their instance providers:
For virtual machines (openstackvms):
shutoff: stopped virtual machine.
active: running virtual machine.
nova: virtual machine that is created directly in OpenStack.
heat: virtual machine created via a Heat template.
vsys: virtual machines created using virtual system patterns (classic).
vsysnext: virtual machines created using virtual system patterns.
vapp: virtual machines created using a virtual application.
vappl: virtual machines created using a virtual appliance.
keynamedefined: virtual machines having an SSH key defined for
access.
For Stacks (heat):
createcomplete: Heat stack instances that are created and are ready to
use.

328

IBM Cloud Orchestrator 2.4.0.2: User's Guide

createfailed: Heat stack instances that failed to be created.

For Volumes (volumes):
available: volumes ready for use.
cinder: all volumes that are created as OpenStack Cinder volumes.
in-use: volumes that are already occupied or used by virtual machines.
formatted: volumes that are formatted.
For Domains (domain):
disabled: domains not ready for use (disabled).
enabled: domains that are enabled for use.
For Projects (project):
disabled: projects not ready for use (disabled).
enabled: projects that are enabled for use.
For Users (user):
disabled: users not ready for use (disabled).
enabled: users that are enabled for use.
For Offerings (offering):
offering: a resource which is of type offering.
For Action Registry (action):
multiInstanceAction: actions performed on multiple instances.
singleInstanceAction: actions performed on a single instance.
For Categories (categories):
Not applicable.

Results
A message appears indicating that the action is created successfully.

Modifying the access control list of an action

You can modify the access control list of an action by adding or removing access.

Procedure
1. Log in to the Self-service user interface as a Service Designer.
2. In the navigation menu, click CONFIGURATION > Actions Registry.
3. Click Modify Access Control List in the Actions menu. The Modify Access
Control List window appears displaying the list of the roles in the specified
domain and project that have access rights to the action.
4. You can perform the following actions:
v To create a new entry in the list, specify the a domain, a project, a role, and
select the appropriate access rights. Click Add to Access Control List.
v To remove an access control entry from the list, click the related Delete icon.
5. Click Save.

Chapter 5. Working with self-service

329

330

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 6. Managing virtual images

You can manage virtual images that can be deployed by using IBM Cloud
Orchestrator.
IBM Cloud Orchestrator adopts a modular image creation model to support
different deployment scenarios. A base image that can be deployed through IBM
Cloud Orchestrator is an image that can be deployed through OpenStack. For this
reason, such images are also described as OpenStack-ready images. For more
information about base images, see Creating base images on page 332.
This kind of image is suitable for single instance deployments and deployment of
OpenStack Heat stacks.
To run more complex scenarios in which you might add software to the instance at
deployment time, or embed scalability policies, the base image must be enriched
with additional software, and must adhere to some specific prerequisites. For
additional information, see Creating images to deploy through virtual system
patterns or virtual application patterns on page 337.
Images used in SmartCloud Orchestrator V2.3 can be used in IBM Cloud
Orchestrator for deployment with Virtual System Pattern (Classic).
Virtual System Pattern (Classic), Virtual System Pattern, and Virtual System
Application can also be used with images that are purchased from IBM Cloud
Orchestrator Catalog, with the exception of images for Linux on System z.
IBM Cloud Orchestrator also provides a procedure for advanced users to create
SmartCloud Orchestrator 2.3-like images to use in Virtual System Pattern (Classic).
For additional information see Creating SmartCloud Orchestrator V2.3-like images
(advanced users only) on page 340.
The following table shows the image capabilities depending on the specific image
type.
Table 41. Image types and capabilities
Virtual
System
Pattern
(Classic)

Virtual
System
Pattern

Virtual
Application

U3

U3

U3

Heat
Single Image Template
Multiple disk U
base image1
Add disk at
deployment
time

U2

Add disk
after
deployment4

U2

Add NIC at
deployment
time5

Copyright IBM Corp. 2013, 2015

331

Supported.

Supported only in VMware.

The volume must be created in advance. When creating volumes on a VMware region,
you can decide if the volume should be thin, thick or eagerZeroedThick.
In a VMware region, deciding if a volume needs to be thin/thick or eagerZeroedThick
provisioned relies on the volume type.
For example:
cinder type-create thick_volume
cinder type-key thick_volume set vmware:vmdk_type=thick
The two instructions above create a volume type for thick provisioning. So if you use
them when creating a volume, the volume will be created with thick provisioning

For VMware regions, the volume is thin or thick provisioned depending on value of
the volume type specified for the default_volume_type entry in openstack.config file
on Central Server 3.

Not supported in z/VM.

Network Interface Cards can only be added at deployment time. This can be done
when deploying single instances directly in the Self-service user interface by using
Heat templates or by using the Network Interface Card add-ons if using virtual system
patterns (classic), virtual system patterns, or virtual application patterns.

Creating images for use in IBM Cloud Orchestrator

You can create images for use in IBM Cloud Orchestrator using one of the
following options.

Creating base images

You can create images suitable for single instance deployments or deployment of
OpenStack Heat stacks.
To create these images, follow the instructions in the Create images manually
chapter in the OpenStack Virtual Machine Image Guide.
Note: This kind of images cannot be used for Virtual System Patterns, Virtual
Application Patterns, or Virtual System Patterns (classic).
After the operating system is installed, you must install the cloud-init software for
customizing the instances deployed using this image, by performing one of the
following procedures:
v Creating Windows base images on page 333
v Adding cloud-init to Linux images on page 336
v Adding cloud-init to images for Linux on System z on page 336
For information on how to build AIX images or images for Linux on Power, see
http://www-01.ibm.com/support/knowledgecenter/SSXK2N_1.2.1/
com.ibm.powervc.standard.help.doc/powervc_images_hmc.html?lang=en
cloud-init is not supported on AIX. You can perform basic deployments only
(such as plain operating system plus IP address assignment) unless you use Virtual
System Patterns (classic), Virtual System Patterns, or Virtual Application Patterns.

332

IBM Cloud Orchestrator 2.4.0.2: User's Guide

For information about creating images for Amazon EC2, SoftLayer and non-IBM
supplied OpenStack via the Public Cloud Gateway, see Creating a supported
image on page 676.
To use Linux images as part of Heat templates it is recommended to install the
heat-cfntools (for additional information see https://wiki.openstack.org/wiki/
Heat/ApplicationDeployment).
Note:
v heat-cfntools are not supported on Linux on System z.
v heat-cfntools for Linux on Power can be downloaded from
http://dl.fedoraproject.org/pub/epel/6Server/ppc64/ for PowerVC images.
When you create a base image, ensure that the image meets the following
prerequisites:
v When you create a Linux image, ensure that you create a single ext3 or ext4
partition (not managed by LVM), otherwise you might have issues when
installing cloud-init.
v If you use a template for a hypervisor that is not VMware, ensure that the image
has a single disk. You can add additional disks at deployment time. For
additional information, see Add-ons in the catalog on page 409.
v When you create a Linux image, ensure that the image has IPv6 networking
disabled. For more information, see the documentation related to your Linux
distribution.
v When creating a Linux image for Hyper-V, make sure that the kernel parameter
no_timer_check is specified to the kernel parameters in the bootloader
configuration. Without this option, your image may fail to boot due to a
problem validating the system timer. Some linux distribution versions may
enable this option automatically when they detect they are running on Hyper-V.
For more information about this kernel parameter, see https://
lists.fedoraproject.org/pipermail/cloud/2014-June/003975.html.

Creating Windows base images

You can create Windows base images by running the following procedures.
Adding cloudbase-init to Windows images:
You can add cloudbase-init to Windows operating system images.
To add cloudbase-init to your image, download it from https://
www.cloudbase.it/downloads/CloudbaseInitSetup_Beta.msi and install it by
following the procedure at http://www.cloudbase.it/cloud-init-for-windowsinstances/.
Note:
v After the cloudbase-init installation, do not select the option to run
sysprep.exe in the Finish page.
v When you create the network, set the dns-nameservers and gateway parameters.
v To speed up the IP address injection, when you create the image template,
specify the metadata_services parameter in the cloudbase-init.conf file:
metadata_services= cloudbaseinit.metadata.services.configdrive.ConfigDriveService,
cloudbaseinit.metadata.services.httpservice.HttpService,
cloudbaseinit.metadata.services.ec2service.EC2Service,
cloudbaseinit.metadata.services.maasservice.MaaSHttpService
Chapter 6. Managing virtual images

333

v If you get the OS can not be restarted automatically message after changing
the host name, use the latest cloudbase-init version.
v cloudbase-init allows to set password for a user. The user name is configured
at image preparation time and cannot be modified at virtual machine creation
time. You can specify a user name during cloudbase-init installation or in the
cloudbase-init.conf file. If the user does not exist, a new user account is
created at virtual machine initialization time. If there are multiple Windows
users at image preparation time, at virtual machine initialization time password
is changed only for the user specified in the cloudbase-init configuration. Other
user's passwords are not changed.
After cloudbase-init is installed, complete the following procedures.
Installing virtio driver (KVM hypervisor only):
To use Windows operating system images on a KVM hypervisor, install the virtio
driver into the system because OpenStack presents the disk using a VIRTIO
interface while launching the instance.
You can download an virtio-win*.iso file containing the VIRTIO drivers from the
following location: http://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/
bin/
Use virt-manager to connect virtio-win*.iso to the image and update the
network adapter in the virtual machine by completing the following steps:
1. Right-click Computer > Properties > Change settings > Hardware > Device
Manager.
2. Click Network adapter > Update driver software > Browse my computer for
driver software.
3. Select the virtual CD/DVD drive and then select the inf file.
4. Restart the virtual machine.
Running sysprep.exe:
Run sysprep.exe to remove all the unique system information, like computer name
and hardware specific information, from your Windows image.
To run sysprep.exe on Windows 2008 R2, complete the following steps. Refer to
the Microsoft documentation for the other Windows platforms.
1. Download and install the Windows Automated Installation Kit (AIK). You can
download Windows AIK from the Microsoft Download Center:
http://www.microsoft.com/en-us/download/details.aspx?id=9085. Windows
System Image Manager is installed as part of the Windows Automated
Installation Kit (AIK).
2. Copy the install.wim file from the \sources directory of the Windows 2008
R2 installation DVD to the hard disk of the virtual machine.
3. Start the Windows System Image Manager.
4. In the Windows Image pane, right-click Select a Windows image or catalog
file to load the install.wim file you just copied.
5. When a warning that the catalog file cannot be opened is displayed, click Yes
to create a new catalog file. Remember to select the Windows 2008 R2 Edition.
6. In the Answer File pane, right-click to create a new answer file:
Language and Country or Region:

334

IBM Cloud Orchestrator 2.4.0.2: User's Guide

a. Generate the answer file from the Windows System Image Manager by
expanding Components in your Windows Image pane, right-click and add
the Microsoft-Windows-International-Core setting to Pass 7 oobeSystem.
b. In your Answer File pane, configure the InputLocale, SystemLocale,
UILanguage, and UserLocale with the appropriate settings for your
language and country or region.
Administrator Password:
v In the Windows Image panel, expand the Microsoft-Windows-Shell-Setup
component, and expand User Accounts, right-click on
AdministratorPassword, and add the setting to the Pass 7 oobeSystem
configuration pass of your answer file.
v In the Answer File panel, specify a password next to Value.
Note: You can read the AIK documentation and set more options
depending on your deployment. The steps described here are the minimum
needed for the Windows unattended setup.
Software License Terms:
In the Windows Image panel, expand Components and find the
Microsoft-Windows-Shell-Setup component. Highlight the OOBE setting, and
add the setting to the Pass 7 oobeSystem. In the Answer File panel, set
HideEULAPage true in OOBE settings.
Product Key and Computer Name:
v In the Windows Image panel, right-click on the Microsoft-Windows-ShellSetupcomponent and add the settings to the Pass 4 specialize configuration
pass of your answer file.
v In the Answer File panel, enter your Product Key in the space provided
next to ProductKey. Furthermore, to automate the Computer Name
Selection page, specify a computer name next to ComputerName.
7. Save the answer file as unattend.xml. Ignore the warning messages that
appear in the validation window.
8. Copy the unattend.xml file into the c:\windows\system32\sysprep directory of
the Windows 2008 R2 Virtual Machine.
9. Clean the environment of the virtual machine.
10. Uninstall Windows AIK which might not be part of the virtual machine you
create.
11. Remove the install.wim file that was copied to the virtual machine.
12. Run the sysprep tool as follows:
cd c:\Windows\System32\sysprep
sysprep.exe /oobe /generalize /shutdown

The Windows 2008 R2 virtual machine shuts down automatically after sysprep is
complete.

Chapter 6. Managing virtual images

335

Adding cloud-init to Linux images

You can add cloud-init to Linux operating system images.
To add cloud-init to your image, set up a YUM repository that holds the
cloud-init RPMs and install them by referring to documentation of your Linux
distribution documentation. For example, for Red Hat, run the following
commands:
yum install cloud-init
yum install cloud-utils
yum install dracut-modules-growroot

After installing cloud-init, enable root login and password authentication by

modifying the following parameters in the /etc/cloud/cloud.cfg configuration
file:
disable_root: 0
ssh_pwauth: 1

For more information, see OpenStack Linux image requirements.

Note: After installing the dracut-modules-growroot package on Red Hat, to
automatically resize the root filesystem when the template is provisioned, run the
mkinitrd command (with option --force, if required) to rebuild the initramfs
used at boot time.
For information about installing cloud-init for Linux on Power, see
http://www-01.ibm.com/support/knowledgecenter/SSXK2N_1.2.1/
com.ibm.powervc.standard.help.doc/powervc_install_cloudinit_hmc.html.
For information about installing cloud-init for Linux on System z, see Adding
cloud-init to images for Linux on System z.

Adding cloud-init to images for Linux on System z

You can add cloud-init to images for Linux on System z.
Specific information on how to build z/VM images is available in chapter 6 of the
Enabling z/VM for OpenStack (Support for OpenStack Icehouse Release) guide at
http://www.vm.ibm.com/sysman/openstk.html.
Note: Reversal of the order of the services startup for z/VM: sshd must be run
before cloud-init.
Service startup order is determined by /etc/rc.d/rc[0-6].d/ directory which
contains symlinks to /etc/init.d/ files. To change startup order, in particular
runlevel, you must change the names of files in the appropriate directory. Scripts
are run by name order so that script with lower number behind letter S starts start
earlier. In z/VM sshd needs to start before cloud-init so it must have a lower
number. Changes must be done for at least the default runlevel, which in RHEL is
3.
To update the RHEL image to make sure cloud-init-local starts after sshd service
is started, perform the following steps:
1. In /etc/init.d/cloud-init-local file, add sshd in the Required-Start
statement:
# Required-Start:

$local_fs $remote_fs xcatconf4z sshd

2. From the command line, run following commands

336

IBM Cloud Orchestrator 2.4.0.2: User's Guide

chkconfig cloud-init-local off

chkconfig cloud-init-local on

Creating images to deploy through virtual system patterns or

virtual application patterns
You can create an image that can be used for virtual systems patterns or virtual
application patterns.
Choose one of the following options:
v Use a base image as described in Creating base images on page 332.
v Use a SmartCloud Orchestrator V2.3 image.
The list of supported platforms shrinks with respect to the plain OpenStack
images. For more information, see table 2 in Software prerequisites on page 21.
For information on enabling Amazon EC2, Softlayer and non-IBM supplied
OpenStack images for pattern deployment via the Public Cloud Gateway, see
Creating Workload Deployer cloud images for Linux on page 677.
Whether you are using a base image or a SmartCloud Orchestrator V2.3 image,
you must install additional software on the image and run some operating system
configuration as explained in the following topics:

Software prerequisites for Linux images (KVM or VMware

hypervisors)
Ensure that the software requirements are met before you create a Linux image.
To create the image, see Creating base images on page 332 or use a SmartCloud
Orchestrator V2.3 image.
Note: SELinux must be disabled.
The following software must be installed:
v curl
v
v
v
v
v
v
v

python 2.X (2.6.2 or later)

sed
dos2unix
openssl (at least version 1.0.0o or 1.0.1i)
ksh
compat-libstdc++
glibc.i686

v libgcc.i686
v compat-libstdc++-33.i686
v nss-softokn-freebl.i686
The following Python modules must be installed:
v base64
v gettext
v hashlib
v pycurl
v ssl
Chapter 6. Managing virtual images

337

The specified Python modules are provided in the following RPM packages:
v Red Hat Enterprise Linux
python
python-pycurl
v SUSE Linux Enterprise Server
python
python-base
python-curl
Note: In the Linux image, if the /etc/sudoers file contains the following line:
Defaults

requiretty

you must comment it out or change it to:

Defaults

!requiretty

Software prerequisites for Microsoft Windows images

Ensure that the software requirements are met before you create a Microsoft
Windows image.
To create the image, see Creating base images on page 332 or use a SmartCloud
Orchestrator V2.3 image.
The following software must be installed:
v
v
v
v
v

Microsoft Visual C++ 2008 Redistributable (x64)

OpenSLL (for example, Win64OpenSSL-1_0_1g.exe)
Curl 32bit (for example, curl-7.36.0-win32-fix1.msi)
Python 2.X (2.6.2 or later) 32-bit (for example, python-2.7.6.msi)
Python module: pywin32 32-bit (for example, pywin32-218.win32-py2.7.exe)

v Python module: pycurl 32-bit (for example, pycurl-7.19.3.1.win32-py2.7.msi)

Important:
v You must install VMware Tools after Microsoft Visual C++ 2008 Redistributable
is installed. If VMware Tools are already installed, you must uninstall and
reinstall VMware Tools after Microsoft Visual C++ 2008 Redistributable is
installed.
v After installing Python, add the Python installation path to the PATH system
variable.
v Ensure that you disable the Microsoft Windows User Account Control (UAC).

Software prerequisites for images for Linux on System z

Ensure that the software requirements are met before you create an image for
Linux on System z.
To create the image, see Creating base images on page 332.
The following software must be installed:
v gcc
v make
v gtk2.s390
v libXtst.s390
v libstdc++.so.5

338

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v
v
v
v
v

compat-libstdc++-33.s390x
dos2unix.s390x
ksh.s390x
genisoimage.s390x
python 2.X (2.6.2 or later)

v curl
Note: For SUSE Linux Enterprise Server, use following replacements:
v For libXtst.s390, use xorg-x11-libs
v For compat-libstdc++, use libstdc++33
The following Python modules must be installed:
v base64
v gettext
v hashlib
v pycurl
v setuptools
v ssl
The specified Python modules are provided in the following RPM packages:
v Red Hat Enterprise Linux
python
python-pycurl
python-setuptools
v SUSE Linux Enterprise Server
python
python-base
python-curl
python-setuptools

Software prerequisites for AIX images

Ensure that the software requirements are met before you create an AIX image.
To create the image, see Creating base images on page 332 or use a SmartCloud
Orchestrator V2.3 image.
The following software must be installed:
v rpm.rte
v gcc-4.2.0-3.aix6.1.ppc.rpm
v Activation Engine
You can download the rpm.rte fileset from ftp://public.dhe.ibm.com/aix/
freeSoftware/aixtoolbox/INSTALLP/ppc/rpm.rte.
To install it, run the following command:
installp -d <absolute_path_of_the_package> /rpm.rte -acgXY rpm.rte

You can download gcc-4.2.0-3.aix6.1.ppc.rpm fileset from http://www03.ibm.com/systems/power/software/aix/linux/toolbox/alpha.html. Instructions

on how to install the rpm.rte, gcc-4.2.0-3.aix6.1.ppc.rpm and the Workload
Chapter 6. Managing virtual images

339

Deployer enablement packages which includes the Activation Engine can be found
here: Installing AIX enablement package on page 347.
To enable the activation engine, and prepare the virtual machine for capture,
follow the instructions at http://www-01.ibm.com/support/knowledgecenter/
SSXK2N_1.2.1/com.ibm.powervc.standard.help.doc/
powervc_enabling_activation_engine_hmc.html.

Creating SmartCloud Orchestrator V2.3-like images (advanced

users only)
You can create or adapt existing images to deploy as part of Virtual System Pattern
(Classic). This procedure applies to Windows and Linux images for KVM or
VMware hypervisors.

Before you begin

For the list of the supported operating systems, see the KVM and VMware rows in
http://www.ibm.com/support/knowledgecenter/SS4KMC_2.3.0/
com.ibm.sco.doc_2.3/c_os.html.
The image must meet the following prerequisites:
v On Windows, see http://www.ibm.com/support/knowledgecenter/api/
content/SS4KMC_2.3.0/com.ibm.sco.doc_2.3/scenarios/
c_prereq_kvm_vmware_images_win.html.
v On Linux, see http://www.ibm.com/support/knowledgecenter/api/content/
SS4KMC_2.3.0/com.ibm.sco.doc_2.3/scenarios/
c_prereq_kvm_vmware_images.html.

About this task

You can add the activation engine and scp-cloud-init to the image. For details
about the activation engine, see the SmartCloud Orchestrator V2.3 documentation
in the IBM Knowledge Center.
You must have Administrator privileges on Windows and root privileges on Linux.

Procedure
1. Obtain IconImageSynchronizer.zip and ovf-env.xml from the
<downloaded_ibm_cloud_orchestrator_package>/utils/imageSynchronizer/
[Linux/Windows] directory of the installation media.
2. Start an instance of the image.
3. Copy IconImageSynchronizer.zip in an instance directory and unzip it.
4. On Windows run IconImageSynchronizer.cmd and on Linux, give executable
permission to IconImageSynchronizer.sh and run it.
5. Copy ovf-env.xml from the installation media, on Windows under
c:\windows\setup\ibm\AP and on Linux under /opt/IBM/AE/AP.
6. On Windows, run the following command:
c:\windows\setup\ibm\AE.bat --reset -n

On Linux, run the following command:

/opt/IBM/AE/AE.sh -reset -n

7. Shut down the instance.

8. Convert the instance back into an image.

340

IBM Cloud Orchestrator 2.4.0.2: User's Guide

What to do next
To add the image to IBM Cloud Orchestrator, see Using images created for
SmartCloud Orchestrator V2.3 on page 352.

Adding images to IBM Cloud Orchestrator

Base images can be automatically deployed through IBM Cloud Orchestrator as
soon as you register them in Glance. They can be deployed as either single
instances or as part of OpenStack Heat stacks.
Additional actions must taken to use images in virtual system patterns, virtual
application patterns, and virtual system patterns (classic). You must use the
following images:
v Images that are created as described in Creating images to deploy through
virtual system patterns or virtual application patterns on page 337. Do not
register these images in the IBM Cloud Orchestrator user interface. You can
select these images directly from Glance when you create the virtual system
pattern.
v OVA images that are purchased from IBM Cloud Orchestrator Catalog. To use
these images, follow the procedure described in Using OVA images from IBM
Cloud Orchestrator Catalog on KVM or VMware on page 344 or in Using
OVA images from IBM Cloud Orchestrator Catalog on PowerVC regions on
page 345.
v Images for SmartCloud Orchestrator V2.3. To use these images, follow the
procedure described in Using images created for SmartCloud Orchestrator
V2.3 on page 352.
Important: Although OpenStack supports having multiple images in Glance with
the same name in the same region, do not use the same image name in different
regions for images that are not logical copies. Doing so might result in the wrong
image being used at deployment time.

Adding images to your OpenStack environment

You can add images to your OpenStack environment to be used by IBM Cloud
Orchestrator.

About this task

To use an image in IBM Cloud Orchestrator, you must add the image to your
OpenStack environment.
If you are using Linux on System z, follow the instructions in Enabling z/VM for
OpenStack (Support for OpenStack Icehouse Release) guide at http://
www.vm.ibm.com/sysman/openstk.html.
If you are using VMware, you can populate the Glance repository automatically
using the discovery process (see Configuring vmware-discovery on page 114) or
you can add images to the Glance repository manually. If you rely on VMware
discovery, you can skip the remaining part of this section.
If you are using PowerVC, images are displayed in Glance automatically, without
any additional action.

Chapter 6. Managing virtual images

341

If you are using KVM, the only available option is the image in Glance.
To add an image to OpenStack, complete the following steps on the Region Server
where OpenStack is installed:

Procedure
1. Set the environment by running the following command:
source /root/keystonerc

2. Run the following command on one line:

glance image-create
--name image_name
--disk-format disk_format
--container-format container_format
--is-public [True|False]
< image_path

where
image_name
Specifies a name for the new image that you are adding.
disk_format
Specifies one of the following disk formats:
raw

An unstructured disk image format.

qcow2

A disk format supported by the QEMU emulator that can

expand dynamically and supports copy-on-write.

vmdk

For a VMware hypervisor, another common disk format

supported by many common virtual machine monitors.

container-format
Specifies the container format for the image. The acceptable formats
are: aki, ami, ari, bare, and ovf.
--is-public
Specifies whether the image is accessible by other users. The value can
be true or false.
image_path
Specifies the full path of the image to be added.
For more information about the glance image-create command, see the
OpenStack documentation.

342

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Attention: If you are deploying on VMware, specify these additional

properties:
vmware_adaptertype, vmware_ostype, and vmware_disktype.
For example:
glance image-create
--name my_vmware_windows_image
--disk-format vmdk
--container-format bare
--is-public False
--property vmware_disktype="preallocated"
--property vmware_adaptertype="lsiLogic"
--property vmware_ostype="Windows764_Guest"
< /tmp/images_to_create

where vmware_disktype can be sparse|preallocated|streamOptimized, and the

vmware_adaptertype can be ide|busLogic|lsiLogic. VMDK disks converted by
the qemu-img utility are always monolithic sparse VMDK disks with an IDE
adapter type. If the image does not come from the qemu-img utility,
vmware_disktype and vmware_adaptertype might be different.
To determine the image disk type and adapter type from an image file, use the
head -20 vmdk_filename command, and find the createType and
ddb.adapterType in the command output. Currently, the operating system boots
VMDK disks with an IDE adapter type that cannot be attached to a virtual
SCSI controller. Disks with one of the SCSI adapter types (such as busLogic or
lsiLogic) cannot be attached to the IDE controller. Therefore, as the previous
examples show, it is important to set the vmware_adaptertype property correctly.
The default adapter type is lsiLogic, which is SCSI. You can omit the
vmware_adaptertype property only if the image adapter type is lsiLogic.
When you create an image by using the glance image-create command or the
Administration user interface, and the image format is not of raw type, you
must specify the minimum disk space required for the image to run (that is, the
current disk size). The disk size is specified in GB, and the value must be
greater than or equal to the virtual size of the image. You can use the following
command to find the virtual size of an image:
# qemu-img info

Tip: If using the glance image-create command, specify the minimum disk
size by using the --min-disk value option. If using the Administration user
interface, specify the required value in the Minimum Disk (GB) field.
Note: Windows has a different mechanism of interpreting the hardware clock
than Linux does. Therefore the following settings are recommended for a
Windows guest image:
v Set the time zone of the image the same as the compute node.
v Disable time synchronization with Internet inside the image, so that the guest
virtual machine will get its time solely from the hypervisor.
v Set the os_type=windows metadata with the --property option when
registering the image.

Chapter 6. Managing virtual images

343

Using OVA images from IBM Cloud Orchestrator Catalog on KVM or

VMware
You can import OVA images that are purchased from IBM, and use the images in
IBM Cloud Orchestrator.
You can purchase OVA images from the public IBM Cloud Orchestrator Catalog.
Note: The OVA images that are purchased from IBM are not VMware-specific. The
IBM OVA files can be used on KVM regions as well as VMware regions.
To use an OVA image purchased from IBM, complete the following steps:
1. Import the OVA image, and map the image to IBM Cloud Orchestrator, as
follows:
a. Log in to the Self-service user interface as a Service Designer.
b. Click PATTERNS > Pattern Design > Virtual Images.
c. Click Create New.
d. Specify the full path to the OVA file. If the file is on a remote system that
requires authentication, specify the credentials.
You can specify the OVA file location in any of the following ways:
v The path to a local file on the Workload Deployer server
v A remote URL on a HTTP server
v A remote location that can be accessed by the secure copy command (scp)
e. Wait for the image import process to complete. This process can take some
time, depending on image size and location.
f. Accept the image license.
2. Add the image to the OpenStack region, and map the OpenStack image to the
imported virtual image in IBM Cloud Orchestrator, in one of the following
ways:
v If the virtual image is built on a single virtual disk, check out the image disk
file to the OpenStack Image service (Glance), as follows:
a. Log in to the Self-service user interface as a Service Designer.
b. Click PATTERNS > Pattern Design > Virtual Images.
c. In the Name column, click the name of the image that you want to add.
The image details are displayed.
d. In the Available on Locations area, click Manage image locations. The
Virtual Image Locations window opens in a new browser tab.
e. Click Create New to create a new image location.
f. In the "Manage virtual image locations" window, click Perform disk
checkout.
g. Select the regions where you want to add the image, and click Create.
Wait for the operation to complete.
If the checkout operation fails with the following error message, the
virtual image is not built on a single virtual disk:
CWZCA0028E: Checkout of virtual image DB2 AWSE 10.5.0.2 into region RegionKVM
has failed due to the following error: This operation is not supported
for templates with multiple hard disks.

If this error message is displayed, you must manually add and map the
image, as described below.

344

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v If the virtual image is built on multiple virtual disks, you cannot use
OpenStack Glance to manage the image. For such images, you must
manually add and map the image, as follows:
a. Convert the image to the required format, and add the image to the
OpenStack region, as described in Converting an OVA image to VMware
format on page 350.
b. Map the image to IBM Cloud Orchestrator, as described in Mapping the
image created in IBM Cloud Orchestrator on page 352.

Managing PowerVC images

The following topics describe how to manage PowerVC images.

Using OVA images from IBM Cloud Orchestrator Catalog on

PowerVC regions
You can use OVA images that are purchased from IBM Cloud Orchestrator Catalog
on PowerVC regions.

Before you begin

The following AIX images are supported by IBM Cloud Orchestrator:
v IBM OS Image for AIX Systems v2.1 for PureApplication System AIX 7.1
v IBM OS Image for AIX Systems v1.1 for PureApplication System AIX 6.1
Before you use OVA images that are purchased from IBM Cloud Orchestrator
Catalog, use the tar command to uncompress the OVA files. The OVA files can
include an OVF file and a mksysb image, or an OVF file and a raw disk. If the OVA
file includes an OVF file and a mksysb image, you must use Network Installation
Management to restore the mksysb image to obtain a raw disk, as described in
Using a mksysb image to install the base operating system on a NIM client. If the
image is already in raw disk format, follow the instructions below.
Important: Some .raw files are raw images, and some .raw files are compressed
files in .gz format. To identify the file type, run the file command, as shown in the
following example:
file image1.raw

If the OVA file is a compressed file, you must uncompress the OVA file before the
import, to make the file bootable.

Procedure
1. Copy the raw file onto a VIOS, and copy that disk image into a PowerVC
volume to create and populate the disk on the SAN.
2. After the image is copied into a PowerVC volume, use the
powervc-volume-image-import command to import it as an image:
powervc-volume-image-import [-h] --name NAME --os-distro {aix,rhel,sles,ibmi}
--volume VOLUME-ID [--user USER] [--activation-type {ae,cloud-init}] [--ovf OVF]

where os-distro is aix, activation-type is ae, and the OVF file is the one
that you extracted from the OVA file. The image is visible in Glance.
For more information about importing volume-backed images, see
http://www-01.ibm.com/support/knowledgecenter/SSXK2N_1.2.1/

Chapter 6. Managing virtual images

345

com.ibm.powervc.standard.help.doc/
powervc_import_volume_images_hmc.html.
3. You can register the image, as described in Using images created for
SmartCloud Orchestrator V2.3 on page 352.
Alternatively, you can import the OVA file into IBM Cloud Orchestrator, and
then map the file to the actual disk on PowerVC, as follows:
Log in to the Self-service user interface as a Service Designer.
Click PATTERNS > Pattern Design > Virtual Images.
Click Create New.
Specify the full path to the OVA file, and specify the credentials if the file is
on a remote system that requires authentication. Click OK.
e. Link the imported artifact to the disk on PowerVC, as described in
Mapping the image created in IBM Cloud Orchestrator on page 352.

a.
b.
c.
d.

Note: For virtual system patterns (classic), it is not mandatory to import the
OVA into Workload Deployer once the PowerVC image is available in
Glance. It is also not mandatory for user-created Workload Deployer images
for use with virtual system patterns. For more information, see Making
PowerVC images compatible with Workload Deployer. To use
IBM-provided Workload Deployer images in virtual system patterns, import
the OVA image into Workload Deployer and map it to the actual disk on
PowerVC.

Making PowerVC images compatible with Workload Deployer

Create your own images that are compatible with Workload Deployer.
Note: Non IBM PureApplication System images will not work with Workload
Deployer unless the Workload Deployer AIX enablement packages are installed.
To create your own image (not purchased from IBM) and make it compatible with
Workload Deployer, complete the following steps:
1. Deploy an AIX image on PowerVM using your preferred method, for example,
Network Installation Management (NIM).
2. Install the Workload Deployer enablement software:
v Log in to the AIX Virtual Machine using Secure Shell and download the
Workload Deployer AIX enablement package and then install (refer to:
Installing AIX enablement package on page 347).
v For more information on software prerequisites for AIX images, see
Software prerequisites for AIX images on page 339
3. Run Virtual System Activation Engine (VSAE):
v Using the PowerVC documentation, reset VSAE and prepare the system for
capture.
4. Capture the system using PowerVC:
v From the PowerVC User Interface Server Panel, click manage existing and
select your newly deployed Virtual Machine from the list.
v Click capture to generate an image of the instance. The instance should
already be stopped when VSAE was activated in the previous step.
5. Import the image into Workload Deployer.
Note: The following steps are for IBM Supplied Images that were captured
using the PowerVC User Interface.

346

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Apply OVF to existing Images

In some cases you must apply an OVF to an existing image in
PowerVC, such as an IBM PureApplication System image was installed
and captured in PowerVC. In this instance the OVF, created by
PowerVC, is not suitable as it is missing extended parameters. To apply
an OVF to an PowerVC image, perform the following:
6. Grab the Open Virtualization Format (OVF) from the IBM PureApplication
System OVA.
7. Transfer the OVF to the PowerVC server.
8. Edit the Glance image in PowerVC using OVF:
a. Create a PowerVC source file to allow access to keystone
(/root/powervc-source) as in the following example:
export
export
export
export
export
export

OS_USERNAME=<root user>
OS_PASSWORD=<root password>
OS_TENANT_NAME=ibm-default
OS_AUTH_URL=https://<powervcserver>/powervc/openstack/identity/v2.0/
OS_CACERT=/etc/pki/tls/certs/powervc.crt
OS_REGION_NAME=RegionOne

Note: OS_REGION_NAME is the region name of the PowerVC node, not the
region name of the region server. It is RegionOne by default.
b.

Source the file:

source /root/powervc-source

c. Create the auth token:

keystone token-get

Output:
+-----------+----------------------------------------------------+
| Property |
Value
|
+-----------+----------------------------------------------------+
| expires |
2014-08-17T12:11:47Z
|
|
id
| d7c49ff3ee37440189a47daece4ad944
|
| tenant_id | ba1b17e309524fa88177019781e814f5
|
| user_id |
0
|
+-----------+----------------------------------------------------+

Copy the id property into a file named auth-token

d. Get the Glance ID of the image to be used:
glance image-list

Use the ID, the auth-token file, and the <image-name>.ovf files to apply the
OVF to the image:
python /usr/lib/python2.6/site-packages/nova/compute/ibm/configuration_strategy_ovf.py
--ovf <image-name>.ovf --auth_token auth-token --image_id <image-id> --replace

The image is now ready to be used by Workload Deployer.

Installing AIX enablement package

After you have logged into your virtual machine, you can begin installing the AIX
enablement package.

About this task

When you deploy a pattern in IBM Cloud Orchestrator, the launched virtual
machine instance goes through an activation process that configures system
settings, such as network IP addresses, password and NTP server. IBM Cloud
Chapter 6. Managing virtual images

347

Orchestrator installs an agent and related services in the launched virtual machine
instance that orchestrate and execute software configuration. A set of prerequisites
is required in the virtual image in order to successfully activate and bootstrap the
virtual machine instance. The enablement package is used to install and configure
the prerequisites in your virtual image to make it suitable for pattern deployment.
The enablement package includes Activation Engine with operating system
activation utilities, Java Development Kit, pattern engine bootstrap utilities, and an
automated installer script.
You must run all commands using the root user ID. The name of the enablement
package for AIX 6.1 and 7.1 is ae-install-package-aix-version.tgz. Follow these
steps to install the enablement package for your system:

Procedure
1. Obtain the enablement package from its public download site and put it in a
designated location that is accessible from the deployed virtual machines.
2. Before installing the enablement package, add the following products if they
are not currently installed:
v rpm.rte
v gcc-4.2.0-3.aix6.1.ppc.rpm
Note: When you prepare the image, make sure that the right locales are
installed. You can check the installed locales by running the lslpp -l | grep
bos.loc command. To install an additional locale, you must install the related
fileset. For example, if en_US in UTF-8 codepage is needed, you must install
the bos.loc.utf.EN_US fileset.
a. Perform the following steps to install the rpm.rte fileset:
1) Download the rpm.rte fileset from the following location:
ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/INSTALLP/ppc/rpm.rte

2) Check if the fileset has been installed on the system:

# lslpp -l fileset-name

For example:
# lslpp -l rpm.rte

If you see the returned message:

Fileset fileset-name not installed

check if /usr/local/bin is in $PATH. If /usr/local/bin is not in $PATH,

add it to the path as user root, otherwise issue the following command
to install the files:
# installp -d fileset-path -acgXY rpm.rte

For example:
# installp -d /var/tmp/rpm.rte -acgXY rpm.rte

b. Perform the following steps to install the gcc-4.2.0-3.aix6.1.ppc.rpm file:

1) Download gcc-4.2.0-3.aix6.1.ppc.rpm from http://www.ibm.com/
systems/power/software/aix/linux/toolbox/alpha.html
2) Install the rpm.file. For example:
# rpm -ihv gcc-4.2.0-3.aix6.1.ppc.rpm

3. Perform the following steps to install the enablement package

348

IBM Cloud Orchestrator 2.4.0.2: User's Guide

a. On the Virtual Machine, download the IBM OS Pattern Kit from

http://www.ibm.com/developerworks/downloads/ibm/ospatternkit/
index.html.
b. Copy it onto a newly created directory. For example:
# mkdir /var/tmp/ena-pkg
# cd /var/tmp/ena-pkg

c. Extract then enablement package. For example:

# gunzip -c ae-install-package-aix-version.tgz | tar xpvf

d. Use one of the following methods to install the enablement package:

v To install a new virtual application enablement environment, issue the
following commands:
# cd AE_installation
# ./ae-installer-aix.sh 2>&1 | tee ae-installer-aix.sh.log

v To preserve the previously installed Activation Engine base components,

such as Activation Engine, Jython and VMC extension, while the
remaining components, such as, Activation Engine extension for AIX,
virtual application platform and tooling are installed, issue the following
commands:
# cd AE_installation
# ./ae-installer-aix.sh -skipAE 2>&1 | tee ae-installer-aix.sh.log

Installation progress displays on the screen. It is also recorded in the

ae-installer-aix.sh.log file located in the current directory. Examine
the log file to confirm successful installation. Once the installation has
completed, a status report is printed.
e. Optional: Remove the workspace once you have verified the installation.
For example:
# cd /var/tmp
# rm -rf ena-pkg/

Tip:
v The installation also generates the uninstall script, opt/ibm/ae/uninstall/aeuninstall-aix.sh. You can run this script independently to remove the
enablement environment. For example:
# /opt/ibm/ae/uninstall/ae-uninstall-aix.sh 2>&1 | tee /tmp/ae-uninstall-aix.sh.log

v The enablement package install script, ae-installer-aix.sh also runs the

uninstall script prior to the installation. If the uninstallation script does not
exist, a default uninstall step will be performed.

What to do next
To ensure that /etc/hosts is used before a DNS lookup on an AIX system edit the
/etc/netsrv.conf file and add the following line if not already present:
hosts = local, bind

Edit the netcd service configuration file to only cache DNS queries. If the
/etc/netcd.conf file does not exist create it. Add the following line to
/etc/netcd.conf:
cache dns hosts 128 0

Ensure that curl is available by running the curl command. If the command is not
found, add it to the system path.

Chapter 6. Managing virtual images

349

Note: Custom AIX deployment might fail on a virtual system pattern due to a curl
error curl: (6) Couldn't resolve host IBMWorkloadDeployer. Failed to update status:
6 and the status of the pattern might hang. During deployment the IBM Workload
Deployer has been added to the /etc/hosts file pointing to Central Server 3,
however the /etc/hosts file might not being used immediately and this might
cause the curl command to fail. To prevent this situation it is necessary to add IBM
Workload Deployer as a new entry in existing DNS server configuration pointing
to Central Server 3.

Converting an OVA image to VMware format

Use the OVA converter tool to transform the IBM Hypervisor Edition OVA images
into a format that can be used by VMware vSphere.

Before you begin

You can deploy an OVA image on VMware in the following ways:
v Manually: use the VMware Open Virtualization Format Tool (the ovftool
command).
v Automatically: use the OVA converter script (ibm_ova_converter.py) to invoke
the ovftool command.
The ibm_ova_converter.py script is in the installation_images/utils/iwd_utils
directory, where installation_images is the directory where you unpacked the
IBM Cloud Orchestrator installation packages, for example, /opt/ico_install.
To run the OVA converter tool, you must have the following prerequisites installed:
v Python version 2.6 or 2.7
v Gunzip
v VMware Open Virtualization Format Tool version 3.5.2 (https://
my.vmware.com/web/vmware/details?downloadGroup=OVFTOOL352
&productId=353)

Procedure
1. Deploy the image in either of the following ways:
v Manually:
a. Convert the OVA file to an OVF directory that can be used by the
VMware ovftool command, by running the following command on one
line:
python ibm_ova_converter.py --file ova_path
[--temp-dir output_dir]

The converter script produces an OVF directory with the same name as
the source OVA file, without file extension.
b. Change directory to the OVF directory:
cd ova_converter_output

c. Use the VMware ovftool command to deploy the output OVF on

VMware vSphere, by running the following command on one line:
ovftool --noSSLVerify --skipManifestCheck --acceptAllEulas
--datastore=vmware_datastore
ova_converter_output.ovf
"vi://vmware_user:vmware_password@vmware_host/vmware_datacenter/host/vmware_cluster/"

v Automatically:

350

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Convert the OVA file and deploy the image on VMware automatically, by
running the following command on one line:
python ibm_ova_converter.py --file ova_path
[--temp-dir output_dir]
--user vmware_user
--password vmware_password
--host vmware_host
--datacenter vmware_datacenter
--cluster vmware_cluster
--datastore vmware_datastore
[--template-name template_name]

where:
ova_path
The full path name of the OVA file to be converted.
output_dir
The target directory where the converted OVF directory is to be placed.
If this optional parameter is not specified, the output is stored in the
same location as the source OVA file.
ova_converter_output
The OVF directory created by the OVA converter tool. The
ova_converter_output.ovf file is located in this directory.
vmware_user
The VMware user name.
vmware_password
The password for the specified VMware user.
vmware_host
The host name or IP address of the VMware vSphere.
vmware_datacenter
The name of the target datacenter on VMware where the image is to be
deployed.
vmware_cluster
The name of the target cluster on VMware where the image is to be
deployed.
vmware_datastore
The name of the target datastore on VMware where the image is to be
deployed.
template_name
The template name to be used when deploying the image to VMware.
If this optional parameter is not specified, the OVA file name is used.
2. After the OVF is deployed in VMware, disable the vApp options of the virtual
machine. To do this:
a. Log on to the VMware vSphere client.
b. Open the inventory of the virtual machines and templates.
c. Select the virtual machine that has been deployed from OVA image.
d. Right-click on the virtual machine and select Edit Settings.
e. Select the vApp Options tab and disable the Enable vApp Options setting.
f. Click OK to save virtual machine settings and close the dialog.
3. Convert the virtual machine to a template in VMware. To do this:
a. Log on to the VMware vSphere Client.
Chapter 6. Managing virtual images

351

b. Open the virtual machines and templates inventory.

c. Select the virtual machine deployed from OVA image.
d. Right-click on the virtual machine and select All vCenter Actions >
Convert to Template.
4. Wait for the template to be discovered in Glance.

Mapping the image created in IBM Cloud Orchestrator

You must map the image created IBM Cloud Orchestrator.

About this task

After the image is available in Glance, you must match the metadata stored in IBM
Cloud Orchestrator when the image was created in the Self-service user interface,
with the actual image in Glance. Perform the following steps:

Procedure
1. Log in to the Self-service user interface as a user with admin or catalogeditor
role.
2. Click PATTERNS > Pattern Design > Virtual Images.
3. Select the image that corresponds to your OVA file and, in Available on
Locations, click Managed image locations.
4. Click Create New and select Create image mapping.
5. Select the region in the Region menu and then select the row corresponding to
the image in Glance.
6. Click Create.

Results
The image is ready to be used in virtual system patterns (classic), virtual system
patterns, or virtual application patterns.

Using images created for SmartCloud Orchestrator V2.3

About this task
You can use images created for SmartCloud Orchestrator V2.3 only as part of
virtual system patterns (classic). After they have been added to Glance, you must
register them in the Self-service user interface. You can perform this action if you
are in admin or catalogeditor role.

Procedure
1. Click PATTERNS > Pattern Design > Virtual Images.
2. Click Register OpenStack image and type in the name of the image or use the
lookup function to find it in Glance.
3. Select the operating system in the list and click Register.
Note: Images for Linux on System z cannot be used for virtual system patterns
(classic).

352

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 7. Managing and deploying virtual patterns

You can perform a variety of tasks on virtual applications, virtual systems, and
shared services.

Virtual pattern types

The types of virtual patterns are: virtual system patterns (classic), virtual system
patterns, virtual application patterns, and shared services. These patterns consist of
parts which are virtual machines and scripts running on those virtual machines.
Virtual system pattern (classic)
A virtual system instance is a collection of virtual machines. Each virtual
machine in a virtual system instance represents a physical node in an
application server environment. For more information about virtual system
patterns (classic), see Working with virtual system patterns (classic) on
page 434.
Virtual system pattern
It is a virtual system pattern (classic) with the following additional
enhancements:
v The operating system and middleware are managed separately. You can
customize an operating system image once and reuse it. Then, you can
use software components to install middleware on the image.
v You can use dynamic scaling policies to define quality of service levels
for software artifacts in the virtual system. Policies can be applied
globally at the pattern level or specified for individual components.
v You can set versions for virtual system patterns, script packages, and
add-ons to manage these assets when they change.
v Virtual system patterns are built and deployed on the same underlying
architecture as virtual application patterns. You have the same control
over the topology and configuration as before, but you can also build
virtual system patterns and manage your deployed virtual system
patterns with the tools that were previously available only for virtual
application patterns, such as the Pattern Editor.
For more information about virtual system patterns, see Working with
virtual system patterns on page 419.
Virtual application pattern
It is a complete set of platform resources that fulfill a business need,
including web applications, databases, user registries, messaging services,
and transaction processes. For more information about virtual application
patterns, see Working with virtual applications on page 498.
Shared service
Shared services provide a predefined virtual application pattern that is
deployed and shared by multiple application deployments in the cloud,
including virtual applications, virtual systems, and virtual appliances. For
more information about shared services, see Working with shared
services on page 652.
For more information about virtual pattern types, see Managing pattern types on
page 492.
Copyright IBM Corp. 2013, 2015

353

Managing environment profiles

You can use environment profiles to control some aspects of your deployment. You
can use environment profiles to group related deployment configuration options
together and deploy from a single pattern.

Environment profiles overview

Environment profiles group related deployment configuration, like virtual machine
names, IP address assignment, and cloud groups. Deploying patterns with
environment profiles enables deployments across tiers from a single pattern.
An environment profile provides configuration that can be used when deploying a
pattern. An environment can be specified with multiple clouds, and specific
resources within those clouds, in IBM Cloud Orchestrator. Environment profiles
provide the following function:
v Defining the operational environments, for example development, test, or quality
assurance
v Defining virtual machine naming conventions within the operational
environment
v Specifying whether IBM Cloud Orchestrator or the pattern deployer provides the
IP address on the deployment
v Segmenting the clouds, and IP groups within the clouds, to specific
environments
v Assigning aliases to the cloud resources such as clouds and IP groups
v Assigning sections within the clouds to specific users or groups
Environment profiles provide an option to deploy a pattern to a specified cloud
group. You can define profile information for the cloud, IP group, and IP address
at a part level in an environment profile. You can select specific IP groups for each
cloud and provide aliases to the cloud and IP groups to better describe the
environment at deployment time. You can use the same pattern and deploy in
different environments without changing the pattern.
The virtual machine name syntax is also specific to the cloud.
Related tasks:
Managing environment profiles in the user interface on page 355
You can manage environment profiles with the IBM Cloud Orchestrator user
interface from the Environment Profiles window.
Related reference:
Environment profiles REST API on page 950
You can use the representational state transfer (REST) application programming
interface (API) to manage environment profiles.

354

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Managing environment profiles in the user interface

You can manage environment profiles with the IBM Cloud Orchestrator user
interface from the Environment Profiles window.

Before you begin

You must have a cloud group configured and ready, with all hypervisors
configured and available to create an environment profile that is ready to be
deployed.

About this task

You can use environment profiles to group related deployment configuration, like
virtual machine names, IP address assignment, and cloud groups, with the IBM
Cloud Orchestrator user interface.

Procedure
1. Click PATTERNS > Deployer Configuration > Environment Profiles on the
menu bar to open the Environment Profiles window.
2. Work with a profile. You can perform the following tasks:
v Create an environment profile with the information in Creating an
environment profile.
v Clone an existing environment profile for reuse with the information in
Cloning an environment profile on page 359.
v Edit an existing environment profile with the information in Editing an
environment profile on page 360.

Creating an environment profile

You can create an environment profile with the IBM Cloud Orchestrator user
interface.

Before you begin

You must have a cloud group configured and ready, with all hypervisors
configured and available, to create an environment profile that is ready to be
deployed.

About this task

You can create an environment profile with the steps in this task.

Procedure
1. From the upper left panel of the Environment profiles window, click New to
add an environment profile.
2. Provide the following basic information about the environment profile you are
creating:
Name Enter a unique name for the profile in the Name field. This information
is required.
Description
Optionally, enter a detailed description to identify the profile in the
Description field.

Chapter 7. Managing and deploying virtual patterns

355

Hypervisor type
Select OpenStack as the type of hypervisor in the cloud group you are
using.
Environment
Select the environment in which this profile is to be created. The
following options are available:
v
v
v
v
v
v

All
Development
Test
Quality Assurance
Performance
Research

v Production
v Pre-Production
The default value is All.
3. Click OK to create the profile. When the information is processed, you return
to the Environment Profiles view and the profile you created is added to the
list in the left panel. It is selected so that the information about it is shown in
the right panel. For more information about the fields on this panel, see
Environment Profiles window fields on page 362.
4. Complete the configuration. Before the environment profile is ready to use, you
must provide additional configuration information in the following fields:
Virtual machine name format
It must contain one of the following variables:
${hostname}
Replaced with the host name of the virtual machine, for
example: My${hostname}VM.
Note: Underscores are not valid characters in the virtual
machine hostname.
${vs-name}
Replaced with the name of the virtual system instance, for
example: My${vs-name}VM. This variable cannot be used alone in
the Virtual machine name format field. The ${vs-name}
variable must be used with one of the other formatting
variables. Otherwise, if a cluster pattern is being deployed, all
virtual machines would then have the same name and the
deployment would fail.
${x-counter}
Replaced with a counter of x digits, for example:
MyVM${3-counter}. The x in this example represents the number
of digits for the counter. So if the value of x is two, then it is
represented as 02. This value could be 01, 02 or 03, for example.
IP addresses provided by
Choose whether you want the IP address for a virtual machine to be
provided by IBM Cloud Orchestrator or specified when the pattern is
being deployed. Use the following options:

356

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Pattern deployer
To provide the IP address for a virtual machine at deployment,
you must also specify the following information for each part:
v
v
v
v

Cloud group
IP group
Host name
IP address

Important: If you choose this option, then you cannot specify

an IP address that is contained within the IP groups that are
defined in IBM Cloud Orchestrator at deployment.
IP Groups
If IBM Cloud Orchestrator is to provide the IP address for a
virtual machine, then you specify only the cloud group and IP
group. Specify these options when you define the parts to
deploy the pattern. IBM Cloud Orchestrator provides the IP
address information.
Deploy to cloud groups
Click this field to select cloud groups that are configured and ready for
use. Only valid cloud groups that are configured with the correct
hypervisor type are available. Selecting a cloud group provides the
following information for the IP groups in that cloud group:
In use Click this check box to use the IP group in the environment
profile.
Name Shows the name of the IP group in the cloud you selected.
Alias

You can specify an alias name for the IP group for use in the
environment profile. The default setting is the actual name of
the IP group.

Subnet address
Shows the subnet address of the IP group.
Gateway
Shows the gateway address of the IP group.
Netmask
Shows the netmask address of the IP group.
Windows domain information
The Windows domain section in the environment profile is optional. If
the Domain name field is empty, other fields in the section will be
ignored, and the deployed system will not be added to a domain. If the
Domain name field is specified, the User name and Password fields
become mandatory. However, the Organizational unit field remains
optional. If the Organizational unit field is not specified, the computer
account will be stored in the default Computers container located under
the Active Directory domain root.
Important: Windows computer names must be 15 characters or less in
length and are derived from the corresponding host names in DNS.
DNS host names, which are more than 15 characters in length, may
cause duplicate computer names by keeping the first 15 characters of
the DNS host names. In the case of a duplicate computer name, when
the computer is joined to an Active Directory domain, it will either
Chapter 7. Managing and deploying virtual patterns

357

replace the existing computer account or result in an error indicating

that the account already exists. Since both are undesirable results, it is
recommended that DNS host names be 15 characters or less in length.
Provide the following domain information:
Domain name
Specify the name of the domain to join, for example,
cloud.company.com.
User name
Specify the user name that is authorized to add a computer
account to the domain. Refer to Microsoft documentation for
details.
Password
Specify the password of the domain user specified in User
name.
Organizational unit
Specify the organizational units where the computer account is
stored. For
example: ou=Computers,ou=ou1,dc=cloud,dc=company,dc=com
where Computers and ou1 are the organizational units created
under the Active Directory domain root, and cloud, company,
and com are derived from the domain name cloud.company.com.
Windows key management service
Provide the following KMS server information to be used for KMS
client activation:
KMS server IP address
Specify the IP address of the KMS server in your environment.
KMS server port
Specify the port used for KMS service.
Environment limits
The environment limits section enables you to provide the limits of the
virtual CPU, virtual memory, and storage that this environment profile
can use on the hypervisor. To provide virtual CPU, virtual memory, and
storage limits, click the number in the limit column.
Note: IBM Cloud Orchestrator does not report information related to
reserved resources and limits associated to the resource pool in
VMware. By default, the resource pool is considered as unlimited. Use
the environment profile in IBM Cloud Orchestrator to manage these
resource limits.
Access granted to...
Click this field to specify access to this environment profile for other
users. Select users to make the environment profile readable or writable
to these users. Initially this field is set to the role of the owner of the
environment profile.
By default, the Add more box contains the Everyone built-in project.
When a project has been added, click the link beside the entry to toggle
between the following access levels:
v Read
v Write
v All

358

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Click the link name of the project to show information about that
project. You can also click the remove link to remove access for a
project.

Results
When you have completed these steps, you have configured basic information
about the environment profile.

What to do next
If there are no errors and all the resources the environment profile contains are
operational, you can deploy it to the cloud or clouds you specified.

Cloning an environment profile

You can clone environment profiles that are created in IBM Cloud Orchestrator
with the user interface. Cloning an environment profile provides a starting point
for configuring a new environment profile as you can reuse some of the existing
configuration.

Before you begin

Select an environment profile that most closely meets your needs, with the
hypervisor type you want to use. The hypervisor type cannot be changed when
you clone an environment profile.
If the profile is to deploy in a cloud other than the one specified in the profile you
are cloning, have a cloud group configured and ready. All hypervisors must be
configured and available in a cloud to create an environment profile that is ready
to be deployed.

About this task

This task provides the necessary steps to clone an environment profile and then
customize the copy to meet the needs of your environment.

Procedure
1. From the left panel of the Environment Profiles window, click the profile you
want to clone. The description and general information about this environment
profile display in the right panel of the Environment Profiles view.
2. Clone the environment profile. Click the clone icon on the upper right panel of
the Environment Profiles view.
3. Provide the following basic information about the new environment profile you
are cloning:
Name Enter a new unique name for the environment profile in the Name
field. This information is required.
Description
Optionally, enter a detailed description to identify and differentiate the
environment profile in the Description field.
4. Click OK to save your changes. When the information is processed, you return
to the Environment Profiles view and the profile you created is added to the
list in the left panel. It is selected so that the information about it is shown in
the right panel. For more information about the fields on this panel, see
Environment Profiles window fields on page 362.
Chapter 7. Managing and deploying virtual patterns

359

5. Edit the environment profile. You can edit the fields described in Editing an
environment profile.

Results
When you have completed these steps, you have cloned and customized the
environment profile.

Editing an environment profile

You can edit some of the configuration for any environment profile to which you
have access. You can modify environment profiles to suit the changing needs of
your environment.

About this task

You can use environment profiles to track CPU, memory, storage and stop
deployments at a particular size. If you have administrative permission, you can
change the high water marks accordingly. Each profile can indicate how many
resources of the cloud IBM Cloud Orchestrator can consume. This task provides
information about the configuration that you can edit for existing environment
profiles.

Procedure
1. From the left panel of the Environment Profiles window, select the environment
profile to edit. The information about that environment profile is shown in the
right panel of the Environment Profiles view.
2. Optional: Determine your access. If you are not able to edit the environment
profile, check the Access granted to: field on the lower right panel to verify
that you have access. If you do not have access, you can click the link on the
owner, view the contact information, and contact the owner to ask for access.
3. Optional: Edit the following configuration information:
a. Edit the description. Add or change the description of the environment
profile in the Description field.
a. Change the environment. Select a different environment, in which your
environment profile is to run, in the Environment field. The following
options are available:
v All
v Development
v Test
v Quality Assurance
v Performance
v Research
v Production
v Pre-Production
b. Specify or change the format of the virtual machine name. In the Virtual
machine name format field, you can specify the format for the virtual
machine name, for example d_${hostname}.
c. Specify how the IP addresses are provided. In the IP addresses provided by
field, select one of the following options to specify how the IP addresses are
provided:

360

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Important: You cannot modify this field once an instance has been
deployed to the cloud. You must create a new environment profile with
your desired setting for the field IP addresses provided by.
Pattern deployer
If you choose to provide the IP address for a virtual machine at
deployment, then you must also specify the cloud group, IP group,
host name, and IP address for each part.
Important: If you choose this option, then the person deploying the
pattern cannot specify an IP address that is contained within the IP
groups that are defined in IBM Cloud Orchestrator.
IP Groups
If IBM Cloud Orchestrator provides the IP address for a virtual
machine, you only specify the cloud group and IP group for the
pattern parts. IBM Cloud Orchestrator provides the IP address
information
d. Add, remove, or change the alias name for the cloud group in which the
environment profile is to run.
Add

To add a cloud group, click the entry field under the Deploy to
cloud groups label and select the cloud group to add.

Remove
Click the Remove link beside any listed cloud groups to remove
them from the environment profile.
Change alias name
In the Alias field, change the name of the cloud. This name is
shown at deployment.
e. Add, remove, or rename IP groups. Select or clear the In use box to indicate
the IP groups in each cloud group to be used. You can also change the
name of the IP group, as it is shown at deployment, in the Alias field.
f. Expand the Windows domain information field, to modify the domain
information.
g. Expand the Windows key management service field, to modify the KMS
server information.
h. In the Environment limits field, you can modify the limits of the virtual
CPU, virtual memory, and storage.
i. Grant or remove access to the environment profile to projects. Use the
Access granted to field to add, remove, or change access to this environment
profile.

Results
If the hypervisors and resources for the cloud group specified are available, the
environment profile can be deployed to the cloud group.

Chapter 7. Managing and deploying virtual patterns

361

Environment Profiles window fields

The Environment Profiles window provides fields to group related deployment
configuration options, like virtual machine names, IP address assignment, and
cloud groups, together. With this configuration information grouped, you can
manage the configuration in the environment profile without changing the pattern
that is deploying the environment profile.
The following icons are on the upper right top bar of the Environment Profiles
window:
Refresh
Refreshes the profile display in the configuration panel after any changes.
Clone Clones the selected profile. You can clone the profile and then edit the
copy.
Delete Deletes the profile from IBM Cloud Orchestrator.
There are two interactive panels of the Environment Profiles window:
Left panel
The left panel provides the following function:
v The New button to create new environment profiles
v A search function to locate existing environment profiles
v A list of environment profiles that have been created
Right panel
The right panel provides the fields to define and view details about a
selected environment profile.
The fields on the right panel of the Environment Profiles window provide details
about an environment profile selected from the listing on the left panel. The
following fields define the selected environment profile:
Description
An editable field that provides the description of the profile. The
description can be added or edited after the environment profile is created.
Hypervisor type
Shows OpenStack as the type of hypervisor with which the profile was
created.
Environment
The environment is specified when the environment profile is created but it
can be changed. The following environments can be specified:
v All
v Development
v Test
v Quality Assurance
v Performance
v Research
v Production
v Pre-Production
The default value is All.
Created on
Shows the time stamp when the profile was created.

362

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Current status
Provides the status of the profile. This field shows if the environment
profile is complete or if information is needed.
The success icon
The success icon indicates that the environment profile is complete
and resources are available.
The warning icon
The warning icon indicates that environment profile is incomplete.
A textual explanation, in addition to the warning icon, provides an
explanation of the problem, or problems, with the environment
profile configuration.
Updated on
Shows the timestamp of the most recent update.
Virtual machine name format
This optional field is a free form editing space to indicate the format of the
virtual machine, for example, d_${hostname}. This field displays None
provided initially.
IP addresses provided by
This field provides the following options:
IP Groups
Indicates that the IP address is to be provided by IBM Cloud
Orchestrator at deployment. IP Groups is the default setting.
Pattern deployer
Indicates that the IP address is to be provided by the person
deploying the pattern at the time of deployment.
Important: If this option is selected, the person deploying the
pattern cannot specify an IP address that is contained within IP
groups that are defined in IBM Cloud Orchestrator.
Deploy to cloud groups
Shows the following information for each cloud group in the list:
Name Shows the name of the IP group in the selected cloud.
Alias

An entry field to specify an alias for the IP group for use in the
environment profile. The default setting is the actual name of the
IP group. Click to change the alias name.

remove
Removes the cloud group from the environment profile.
Clicking the expand icon shows the following additional fields for the
selected cloud group:
Using Environment profile
Selection box to specify the IP group to use.
Name The name of the cloud group.
Deploy to cloud groups
The cloud groups to which this environment profile can deploy.
Subnet address
Shows the subnet address of the IP group.

Chapter 7. Managing and deploying virtual patterns

363

Gateway
Shows the gateway address of the IP group.
Netmask
Shows the netmask address of the IP group.
Windows domain information
Shows the following domain information:
Domain name
Shows the name of the domain.
User name
Shows the user name that is authorized to add a computer account
to the domain.
Password
Shows the password of the domain user specified in User name.
Organizational unit
Shows the organizational units where the computer account is
stored.
Windows key management service
Shows the following KMS server information:
KMS server IP address
Shows the IP address of the KMS server in your environment.
KMS server port
Shows the port used for KMS service.
Environment limits
In the table, you can set the following types of environment profile limits:
v Virtual CPU
v Virtual Memory
v Storage
This table also shows the current usage and the reserved usage for each of
these types.
Access granted to
By default, the user who created the environment profile has access to it
and other users cannot edit it. This field can be edited and to provide
access to this environment profile for projects. Selecting projects makes the
environment profile readable or writable to the users belonging to these
projects.
By default, the Add more box contains the Everyone built-in project. When
a project has been added, click the link beside the entry to toggle between
the following access levels:
v Read
v Write
v All
Click the link name of the project to show information about that project.
You can also click the remove link to remove access for a project.
Comments
A comments field is provided to enable administrators to communicate
information with one another regarding environment profiles.

364

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Managing script packages

You can use script packages to customize the behavior of parts in IBM Cloud
Orchestrator topologies by adding script packages to pattern topologies. You can
create script packages and then add them to the part you want to modify within
the pattern containing that part.

Before you begin

You must create a compressed file in .zip or .tgz (.tar.gz) format that contains
the main executable file and all associated artifacts that support the execution of
the main executable file. This will be uploaded into IBM Cloud Orchestrator and
used as input to create the script package. See Script packages overview for
more information about using script packages with IBM Cloud Orchestrator.
The compressed file includes the script file (script.sh on Linux, or script.bat or
script.cmd on Windows) in addition to the .json file needed to run the script on
the deployed virtual machine. For more information, see Configuring script
packages using the cbscript.json object on page 374.

Script packages overview

Script packages can be added to pattern topologies to customize the behavior of
the parts. Patterns are used to define cells and they can include script packages to
further define behavior.
Script packages are simple containers that contain all the required artifacts
necessary to run a script. The script package is a directory compressed into a single
file that is uploaded to the catalog and then associated with patterns. The code
included in the script package can be as simple as a .war file or as complex as a
complete product. The content of a script package is not defined by IBM Cloud
Orchestrator. The script included in the script package defines the required content
for that package.
During deployment, script packages are transferred to the target virtual machines
at a location you specify in the configuration. After they have transferred, they are
extracted in that same location. When the virtual machines successfully start and
are federated (if applicable), script packages are extracted. The scripts are run
using the supplied command line. These files are written to the file system as the
root user. If a different user requires access to these files, ensure that you set the
correct user properties for the files on the guest operating system.
By default, your scripts are run on the deployed virtual machines using the root
user context (on Linux) or administrator (on Windows). You can assume that a
different user context for running the script package should contain a shell script
that performs the following command: su virtuser -c "./nextShellScript.sh".
This command starts a second script that runs in the user context of the virtuser.
By running script packages using this method, you ensure that new files,
directories, and binary files are created with the appropriate user context.
By default, the application server is started before scripts are run. To run a script,
before starting the application server, use the AUTOSTART environment variable. By
default, the AUTOSTART value is set to TRUE (AUTOSTART=TRUE) and the servers are
started before the scripts are run. You can change the default value to FALSE

Chapter 7. Managing and deploying virtual patterns

365

(AUTOSTART=FALSE) to run a script before the server is started. For more information
about environment variables, see Script package environment variables on page
388.
Scripts run in a prescribed order. If you are running an IBM WebSphere
Application Server Hypervisor Edition script on multiple virtual machines, for
example, then the script runs on the virtual machines in the following order:
1. Stand-alone Nodes
2. Deployment Manager
3.
4.
5.
6.
7.

Job Manager (version 7.0.0.x patterns only)

Administrative Agent (version 7.0.0.x patterns only)
Custom Nodes
IBM HTTP Server
On-demand router (if you are using WebSphere Application Server 7.0.0.17 with
Intelligent Management Pack)

If multiple script packages are included with a pattern, by default, the scripts are
run in the same order they were added to that pattern. You can change the order
in which script parts are run in the pattern. For more information, see Ordering
parts to run at deployment on page 446.
When scripts are run by IBM Cloud Orchestrator, the IBM Cloud Orchestrator
establishes a run time environment on the virtual machine using a Secure Shell
(SSH) tunnel (this is valid only on Linux). By default, on the included Linux based
virtual machines, this is the bash directory. This includes the definition of a set of
environment variables. For more information about these environment variables,
see Script package environment variables on page 388.
Script packages remain on the virtual machine after they are run. As they exist on
the virtual machine, you can manually run your scripts from the virtual machine
after deployment. To set the environment variables to run a script manually on the
virtual machine, you must source the /etc/virtualimage.properties file (this is
valid only on Linux). If you want the script package to be removed after it has
run, you can build the script to delete itself.
In addition to the included scripts, you can review the examples that are provided
in the subsection. The examples demonstrate how to use scripts in a virtual
environment.

Using script packages with the user interface

You can use the user interface to manage script packages. You can later add script
packages to parts in system topologies to customize the behavior of virtual system
patterns.

Before you begin

You must create a compressed file in .zip or .tgz (.tar.gz) format that contains
the main executable file and all associated artifacts that support the execution of
the main executable file. This will be uploaded into IBM Cloud Orchestrator and
used as input to create the script package. See Script packages overview on page
365 for more information about using script packages with IBM Cloud
Orchestrator.

366

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The compressed file includes the script file (script.sh on Linux, or script.bat or
script.cmd on Windows) in addition to the .json file needed to run the script on
the deployed virtual machine. For more information, see Configuring script
packages using the cbscript.json object on page 374.

About this task

You can use the user interface to work with script packages.

Procedure
1. Navigate to the Script Packages window by clicking PATTERNS > Pattern
Design > Script Packages from the menu.
2. Perform any of the following tasks:
v Add a script package. For information about adding a script package, see
Adding a script package.
v Making a script package read-only. See Making script packages read-only
on page 371 for more information.
v Associate a script package with a pattern. After adding the script package,
you can associate it with a pattern. For information about associating a script
package with a pattern, see Associating a script package with a pattern on
page 371.
v Delete a script package. If you determine that a script package is no longer
needed, you can delete it. For information about deleting a script package,
see Deleting a script package on page 373.

Results
When the script package is created and associated with a specific pattern, the
script package runs when the pattern is deployed. If you delete a script package, it
is no longer available for use and this operation cannot be undone.

Adding a script package

You can create a script package and associate the script package with a pattern and
defined cell. The script package is added to the catalog through the user interface.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps.
You must create a compressed file in .zip or .tgz (.tar.gz) format that contains
the main executable file and all associated artifacts that support the execution of
the main executable file. This will be uploaded into IBM Cloud Orchestrator and
used as input to create the script package.
Important: When creating your scripts, ensure that you use a text editor that does
not introduce control characters as this causes the scripts to possibly become
unusable.

About this task

Use this task to add a new script package, that you have created, to a part within a
pattern to manipulate the behavior of that part.

Chapter 7. Managing and deploying virtual patterns

367

Procedure
1. From the upper left of the Script Packages window, click Create New.
Additionally, you can clone an existing script package to create a copy of that
script package. The cloned script package can then be modified to your
specification. For more information about cloning a script package, see
Cloning a script package on page 370
2. Select the script package archive and click Import. The new script package
displays in the left panel of the Script Packages window. The right panel
displays configuration options for the script package.
3. Configure the script package.
The script package can be configured manually or by including a special JSON
object in the script package. See Configuring script packages using the
cbscript.json object on page 374 for more information about configuring a
script package using a JSON object.
The following information is required to configure a script package:
Script package files
Specifies the name and location of the compressed file that contains the
script package. Locate the local file system and select this file. After
selecting the file, click Upload to copy the file to IBM Cloud
Orchestrator. Only one file can be uploaded to a script package.
Environment
Defines a set of environment variables that are available when the
script package is run on its target virtual system instance. The
environment variables are a set of key/ value pairs that are defined to
the run time environment of the script. IBM Cloud Orchestrator
supplies a set of environment entries for you.
See Script package environment variables on page 388 for a listing of
available environment variables.
In this section, you can also specify additional values that are specific
to your deployment. The environment variable is added as a parameter
in the pattern. The value for this environment variable is then provided
when you, or another user you have provided with access to the
pattern, deploys the pattern. A default value can be specified in the
pattern.
Working directory
Specifies the location on the target virtual machine that IBM Cloud
Orchestrator extracts the script package. The working directory is also
the initial current working directory when the script is run.
Logging directory
Specifies the location of the logs generated by the script after it has
been run. These logs can be accessed for viewing from either IBM
Cloud Orchestrator or by directly accessing them on the virtual
machine.
Executable
Specifies the command to be started for this script package. This can be
an executable command already on the virtual machine, for example
wsadmin, tar, ant, or another system command. You can also provide
your own script to be run as part of the script package.
Arguments
Specify the command line that is passed to the executable command.
This field can optionally contain environment variables and other valid

368

IBM Cloud Orchestrator 2.4.0.2: User's Guide

command-line syntax. You can also access environment using standard

techniques (for example shell, or ant).
Timeout
Specifies the maximum amount of time (in milliseconds) to wait for this
package to finish running on the virtual machine. The default value is
60000000 (16 hours and 40 minutes).
Executes
Specifies when the script package is run on the product machine. The
default behavior is for the script package to run after all the virtual
machines have successfully started and all the nodes are federated,
where applicable. The default behavior occurs when the virtual system
instance is created. See Script packages overview on page 365 for
more information about when script packages are run.
at virtual system instance creation
Specifies that the script is run when the virtual system has
finished starting during the initial creation.
at virtual system instance creation and when I initiate it
Specifies that the script is run when the virtual system has
finished starting during the initial creation and it can be started
manually using the start icon that is displayed next to the script
name for a virtual machine.
at virtual system instance deletion
Specifies that the script is run when the virtual system is
deleted.
Important: Scripts run at virtual system instance deletion are
only run if the virtual system instance is running when it is
deleted.
when I initiate it
Specifies that the script is started manually using the start icon
that is displayed next to the script name for a virtual machine.
Click the icon to run the script. There is no limit on the number
of times a script is run using this method.
Included in patterns
When you have added the script package to a pattern, a list of the
patterns to which the script package belongs are displayed in this field.
Each pattern name is a link that can be clicked to view the pattern. This
field is initially blank.
See Working with virtual system patterns (classic) on page 434 for
more information about patterns.
In the cloud now
Specifies a list of the cloud instances to which the script package
belongs.
Access granted to
Specifies the users and projects assigned access to this script. Scripts
can be added and used by patterns that are created by these users or
by the users belonging to these projects. Access is automatically granted
to the user that creates the script package. If additional users require
access to the script package, you must manually add the projects to
which these users belong.

Chapter 7. Managing and deploying virtual patterns

369

4. When you have completed the configuration for the script package, the script
package is saved. You can exit from the Script Packages view.

Results
The script package is created and any users with access can use it with patterns.

What to do next
You can now associate this script package with a pattern. For more information
about patterns, see Working with virtual system patterns (classic) on page 434.

Cloning a script package

You can create a script package based on an existing script package. The cloned
script package can then be modified to your specifications.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps.
Important: When creating scripts, ensure that you use a text editor that does not
introduce control characters. Control characters can cause the scripts to become
unusable.

About this task

Use this task to add a clone an existing script package.

Procedure
1. From the left panel of the Script Packages window, locate the script package to
clone. If the script package that you want to clone is not displayed, you can
search for the script package. To search for the script package, on the left panel
of the Script Packages view, enter all or part of the name of the script package
in the search field.
2. Select the script package to clone. Click the script package to clone from the list
on the left panel of the Script Packages view. Details about the script package
are displayed in the right panel of the Script Packages view.
3. Click the clone icon to clone the script package you have selected.
4. Enter the name for the cloned script package and click OK. The details panel
for the new script package displays and can be modified.
5. When you have completed the configuration for the script package, the script
package is saved when you exit the Script Packages view.

Results
After you have completed these steps, users or groups with access, can use the
script package with patterns.

What to do next
You can now associate this script package with a pattern. See Working with
virtual system patterns (classic) on page 434 for more information about patterns.

370

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Making script packages read-only

Either draft or read-only script packages can be deployed for testing or production,
but making a script package read-only prevents further edits. Making script
packages read-only provides consistent reuse in the cloud.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps.

About this task

You can make a script package read-only to prevent further editing to the script
package.

Procedure
1. Select the script package. From the left panel of the Script Packages window,
select the script package. Script packages that have the read-only symbol by
them are already read-only and cannot be edited. Script packages with the edit
symbol beside them are not read-only and can be edited. Basic information
about the selected script package is shown in the right panel of the Script
Packages window.
2. Made the script package read-only to lock it to future editing. Click the Lock
icon in the upper right toolbar of the Script Packages window.
3. Verify that you want to make the script package read-only. When prompted to
verify that you want to make the script package read only, click OK to lock the
script package.

Results
When you have made the script package read-only.

What to do next
You can now associate the script package with a pattern. See Working with virtual
system patterns (classic) on page 434 for more information about patterns.

Associating a script package with a pattern

You can associate a script package with a pattern and defined cell through the user
interface.

Before you begin

You must create and configure the script package before you can associate it with a
pattern. For information about creating and configuring a script package, see
Adding a script package on page 367.

About this task

Use this task to associate a script package with a pattern.

Chapter 7. Managing and deploying virtual patterns

371

Procedure
1. Navigate to the Virtual System Patterns window by clicking PATTERNS >
Pattern Design > Virtual System Patterns for Virtual Systems, or by clicking
PATTERNS > Pattern Design > Virtual System Patterns (Classic) for Virtual
Systems (classic).
2. Select a pattern. In the left panel of the Virtual System Patterns window, select
the pattern with which to associate the script package. The pattern must not be
read-only. For more information about patterns and editing them, see the
Virtual system pattern (classic) editing views and parts on page 443 topic.
Basic information about the selected pattern displays in the right panel of the
Virtual System Patterns view.
3. Edit the pattern. Click Edit on the upper right of the Virtual System Patterns
(classic) window for virtual systems (classic) or click Open on the upper right
of the Virtual System Patterns window for virtual systems (classic) to edit the
pattern.
4. Select Scripts. From the drop-down box in the left panel of the Pattern Editor,
for virtual systems (classic), or in the left panel of the Pattern Builder, for
virtual systems, click Scripts. A list of the script package parts is provided that
can be dropped into the virtual image parts on the right panel of the Pattern
Editor view. This list can contain any script packages that you have provided
for use with IBM Cloud Orchestrator. Script packages can then be added to the
virtual image parts.
5. Add a script package. Any script packages you have defined to IBM Cloud
Orchestrator are available in the list of script packages on the left panel of the
Virtual System Patterns view. You can drop any script package from this list
onto the virtual image parts on the canvas on the right. This associates the
script package with that part.
If a script runs on multiple virtual machines on the pattern, then the script runs
on the virtual machines in the following order:
a. Stand-alone Nodes
b. Deployment Manager
c. Job Manager (version 7.0.0.x patterns only)
d. Administrative Agent (version 7.0.0.x patterns only)
e. Custom Nodes
f. IBM HTTP Server
If multiple script packages are included with a pattern, then the scripts are run
in the same order they were added to that pattern.
6. Optional: Configure any properties defined in the script package. Properties
added to script packages can be defined when associating the script package
with a part or it can be defined during deployment. Click the edit properties
icon to set the value now. It is possible to use a variable syntax to set the value
for properties where the value is not yet known. For more information about
setting the value of a property to be variable, see Properties variable syntax
on page 390

Results
You have added one or more script packages to the virtual images on the pattern.

372

IBM Cloud Orchestrator 2.4.0.2: User's Guide

What to do next
When you have associated the script package with a pattern, you can complete
configuration of the pattern and deploy it to the cloud group.

Deleting a script package

You can manually delete a script package, disassociating it with the pattern and
cell.

Before you begin

You must be assigned the catalogeditor role and be granted all access to the script
package you want to remove. You can also perform these steps if you are assigned
the admin role.
Script packages that are read-only, or that are in use, cannot be deleted. Before you
delete a script package, ensure that it is no longer needed by the pattern and the
cell with which it is associated.

About this task

This task provides information about manually deleting a script package from the
Script Package panel of the IBM Cloud Orchestrator user interface.

Procedure
1. From the left panel of the Script Packages window, locate the script package. If
the script package that you want to delete is not displayed, you can search for
the script package. To search for the script package, from the left panel of the
Script Packages view, enter all or part of the name of the script package in the
search field.
2. Select the script package to delete. Click the script package to delete from the
list on the left panel of the Script Packages view. Details about the script
package are displayed in the right panel of the Script Packages view.
3. Determine if the script package can be deleted. A script package can only be
deleted if it is not:
v Marked as read-only. The read-only icon is displayed in the listing of script
packages if it is read-only.
v Included in any patterns. If it is included in any patterns, the delete icon is
not available and the Included in patterns field displays the linked patterns
for which this script package is included.
If the script package is referenced by any patterns, you can click the pattern
name link in the Included in patterns field to go to the Virtual System Patterns
panel for that pattern. From this panel, you can remove the script package from
the pattern.
4. Delete the package. Click the delete icon on the upper right of the Script
Packages view.
5. Confirm the deletion. You are prompted to confirm that you want to delete the
selected script package. Click OK to delete the script package.

Results
The script package is deleted from IBM Cloud Orchestrator.

Chapter 7. Managing and deploying virtual patterns

373

Configuring script packages using the cbscript.json object

Use a special JSON object, cbscript.json, to include all the information needed to
configure a script package that you add to the catalog.

Overview
When you add a new script package to the catalog, whether by creating a new one
or cloning an existing package and configuring it for your needs, you need to
specify a number of configuration parameters as defined in the Script Packages
pane of the catalog. After uploading your compressed file (.zip and .tgz file types
are supported) containing the main executable file and associated artifacts that
support the execution, configure the various commands and arguments, working
and log files, environment variables needed by the script, and other items that are
required to complete the script package definition.
Even though you can do this manually in the Script Packages pane, a best practice
is to define these configuration settings once in a special JSON object file that you
can include as part of the compressed file before uploading into your script
package. The file must be named cbscript.json, and must be located in the root
directory of the uploaded compressed file.
The cbscript.json object describes the script package and points to the location of
the main script (the script that is the starting point of execution). The
cbscript.json file can also contain all of the configuration parameters that you
would manually specify in the Script Packages pane. When the compressed file
containing the cbscript.json file is uploaded into the script package, the various
fields in the Script Packages pane are populated with the contents of the file.
Including a cbscript.json file in your compressed file helps you to ensure that if
the same script package needs to be reloaded or shared among multiple virtual
system patterns, or if you need to move the virtual system pattern to another
system, its definition will be consistent.
Note: After you upload the compressed file into the script package definition,
refresh the Script Packages pane to display the updated configuration settings from
the cbscript.json file.

Example of a cbscript.json object file

The following example shows the contents of a typical cbscript.json object file, its
basic syntax, and many of the variables that define the configuration settings for
the script package. You can use this example to install an application:
[
{
"name": "Application Install",
"version": "1.0.0",
"description": "This script package installs the specified application",
"command": "/bin/sh ${WAS_PROFILE_ROOT}/bin/wsadmin.sh",
"log": "${WAS_PROFILE_ROOT}/logs/wsadmin.traceout",
"location": "/opt/tmp/installapp",
"timeout": "0",
"commandargs": "-lang jython -f /opt/tmp/installapp/install_app.jy $APP_LOCATION $INSTALL_ARGS",
"ostype": "linux/unix",
"type": "APPLICATION",
"keys":[
{
"scriptkey": "APP_LOCATION",
"scriptvalue": "",
"scriptdefaultvalue": ""

374

IBM Cloud Orchestrator 2.4.0.2: User's Guide

},
{
"scriptkey": "INSTALL_ARGS",
"scriptvalue": "",
"scriptdefaultvalue": ""
}
]
}
]

Parameters in the cbscript.json object

The basic syntax for parameters specified in the cbscript.json object file is of the
form:
"<parameter_name>": "<parameter_value>",

You can specify the following parameters in the cbscript.json object:

name

An optional plain text string that identifies the script package. The value of
this parameter is not displayed in the Script Packages pane when the
compressed file is uploaded to the script package. This name does not
affect the name in the Script Packages pane that you give to the script
package when you create or clone it. The text string can have a maximum
of 1024 characters.
Example:
"name": "Install and configure the ITM OS agent",

When the script package is downloaded, this text string is replaced with
the name of the script package specified in the name field of the Script
Packages pane.
version
An optional plain text string that provides version information. This value
is not used by IBM Cloud Orchestrator and is not displayed in the Script
Packages pane when the compressed file is uploaded into the script
package. If you are the originator of the cbscript.json object file, you
might use this field for internal version control as needed.
Example:
"version": "1.0.0",

When the script package is downloaded, this value is not written in the
cbscript.json file.
description
An optional plain text string that describes the script package function.
This text string is displayed in the Description field of the Script Packages
pane when the compressed script package is uploaded. The text string can
have a maximum of 1024 characters.
Example:
"description": "This script package creates a JDBC Provider and Data Source
for a highly available DB2 Enterprise database cluster",

When the script package is downloaded, this value is written in the

cbscript.json file.
command
An optional command string that runs the main script in the script
package. The value of this parameter is displayed in the Executable field

Chapter 7. Managing and deploying virtual patterns

375

of the Script Packages pane when the compressed script package is

uploaded. The string value can have a maximum of 4098 characters, and
can include environment variables.
Example:
"command": "/bin/sh /tmp/createDB2DataSource/createDB2DataSource.sh",

When the script package is downloaded, this value is written in the

cbscript.json file.
log

An optional location on the virtual machine for log files that are written
resulting from the script package execution. The value of this parameter is
displayed in the Logging directory field of the Script Packages pane when
the compressed script package is uploaded. The string value can have a
maximum of 4098 characters.
Example:
"log": "/tmp/SCAS_scriptpkg_logs",

When the script package is downloaded, this value is written in the

cbscript.json file.
location
The optional location where the script package files are stored and
unpacked when the compressed script package is uploaded. The value of
this parameter is displayed in the Working directory field of the Script
Packages pane when the compressed script package is uploaded. The
string value can have a maximum of 4098 characters. The default value is
/tmp. On supported Windows operating systems, the default is C:\temp.
Example:
"location": "/tmp",

When the script package is downloaded, this value is written in the

cbscript.json file.
timeout
The maximum amount of time, expressed in milliseconds, in which the
script is expected to complete its execution. The value of this parameter is
displayed in the Timeout field of the Script Packages pane when the
compressed script package is uploaded. The default value is 60000000
(1000 minutes). A value of 0 specifies to wait indefinitely for the script to
complete. If the timeout value is exceeded, Status.TIMEOUT_FAILED is
returned, a message is logged to trace.log, and execution is stopped.
Example (timeout value of 2 minutes, specified as 120,000 milliseconds):
"timeout": "120000",

When the script package is downloaded, this value is written in the

cbscript.json file.
execmode
Specifies when the script package is run on the system. The default
behavior is for the script package to run after all the virtual machines have
successfully started and all the nodes are federated, where applicable. The
default behavior occurs when the virtual system instance is created. The
following values are valid for this parameter:
0

376

Specifies that the script is run when the virtual system has finished
starting during the initial creation. This is the default value if this
parameter is not specified.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Specifies that the script is run when the virtual system is deleted.

Specifies that the script is started manually using the start icon that
is displayed next to the script name for a virtual machine. Click the
icon to run the script. There is no limit on the number of times a
script is run using this method.

Specifies that the script is run when the virtual system has finished
starting during the initial creation, and is also available to be
started manually by using the start icon that is displayed next to
the script name for a virtual machine. Click the icon to run the
script. There is no limit on the number of times a script is run
using this method.

Example:
"execmode": "2",

When the script package is downloaded, this value is written in the

cbscript.json file.
ostype The type of operating system for which this script is supported. This
parameter is useful when you need to indicate that the script is valid only
for a specific operating system. The following values are valid for this
parameter:
linux/unix
The script is valid only on supported Linux and UNIX operating
systems. This is the default value if this parameter is not specified.
windows
The script is valid only on supported Windows operating systems.
both

The script is valid on all supported Windows and Linux/UNIX

operating systems.

For example, if you create a virtual system pattern with a Windows

operating system image, any scripts that are included in that pattern must
be able to run on that operating system. In this case you specify the
supported operating system as:
"ostype": "windows",

When the script package is downloaded, this value is written in the

cbscript.json file.
type

An optional indication of the type of script package. The only valid value
(and the default if not specified) is Application. Other values are for internal
use only.
Example:
"type": "APPLICATION",

When the script package is downloaded, this value is written in the

cbscript.json file.
commandargs
An optional list of arguments and their values that are passed to the script
at run time. This list of arguments is displayed in the Arguments field of
the Script Packages pane when the compressed script package is uploaded.
The string can have a maximum of 4098 characters, and can include
environment variables. If the argument can contain the space character, the
argument must be wrapped with double quotes using the backslash as an

Chapter 7. Managing and deploying virtual patterns

377

escape character (\"). When the script package is downloaded, if this

parameter is specified, this string replaces the string in the cbscript.json
file.
Example:
"commandargs": "-user \"$(WAS_USERNAME)\" -password $(WAS_PASSWORD)
-lang jython -f /tmp/myLabApp/appInstall.jy",

keys

The list of environment variables that are added to other system

environment variables and made available to the script at run time. These
environment variables and their values are displayed in the Environment
field of the Script Packages pane when the compressed script package is
uploaded.
The list of environment variables and their values are defined in the
following format:
"keys":
[
{
"scriptkey": "<ENV_NAME>",
"scriptvalue": "",
"scriptdefaultvalue": "<default_env_value>"
},
{
"scriptkey": "<ENV_NAME>",
"scriptvalue": "",
"scriptdefaultvalue": "<default_env_value>",
"locked": "<ENV_LOCK>"
},
{
"scriptkey": "<ENV_NAME>",
"scriptvalue": "",
"scriptdefaultvalue": "<default_env_value>",
"type": "<ENV_TYPE>",
"locked": "<ENV_LOCK>"
}
]

Each environment variable is defined with the following attributes:

scriptkey
The name of the environment variable. This attribute is required.
Example:
"scriptkey": "DATABASE_HOST",

If the text string value of this attribute includes password, the key is
treated the same as if the password type attribute is specified.
Example:
"scriptkey": "DATABASE_PASSWORD",

When the script package is downloaded, this attribute is written to

the cbscript.json file.
scriptvalue
This attribute is currently not used by the system, but is required
to be included for each scriptkey. Set it to an empty string value.
Example:
"scriptvalue": "",

When the script package is downloaded, this attribute is written to

the cbscript.json file.

378

IBM Cloud Orchestrator 2.4.0.2: User's Guide

scriptdefaultvalue
An initial default value for the environment variable that you can
modify later if needed. This attribute is required, but the value can
be blank. If validvalues is specified, the value specified for this
default must be one of the valid values specified in the
validvalues list.
Example:
"scriptdefaultvalue": "mainhost.ibm.com",

When the script package is downloaded, this attribute is written to

the cbscript.json file.
description
An optional plain text string that describes the script key function.
This text string is displayed as descriptive help text for the script
key attribute when you are configuring the script key parameter
for deployment. The text string can have a maximum of 128
characters.
Example:
{
"scriptkey": "NPM_PROXY_URL",
"scriptvalue": "",
"scriptdefaultvalue": "http://192.168.1.1:8080",
"description": "Proxy Server Settings",
"type": "string",
"locked": "false"
}

When the script package is downloaded, this attribute is written to

the cbscript.json file.
type

An optional string indicating the type of environment value. the

following values are valid:
v boolean
v integer
v positiveinteger
v password (the value is obscured in the user interface or in log
files)
v string (this is the default value)
Example:
"type": "password",

When the script package is downloaded, if this attribute is present,

it is written to the cbscript.json file.
locked
An optional control indicating if the environment variable can be
modified at deployment time. Valid values are true or false. The
default value is false.
Example:
"locked": "true",

Note that this locking feature sets the locked state of the parameter
(to locked) when it is added to the Pattern Editor canvas, and is
only in effect at the time of deployment. This setting does not
affect your ability to do any of the following tasks:
Chapter 7. Managing and deploying virtual patterns

379

v Remove the parameter from the script package in the catalog.

v Change the value of the parameter within the script package in
the catalog.
v Reset the parameter to an unlocked state when editing the
package properties in the Pattern Editor.
When the script package is downloaded, this attribute is written to
the cbscript.json file.
required
An optional control indicating if the environment variable is a
required or optional variable. Valid values are true or false. The
default value is true.
Example:
"required": "false",

When the script package is downloaded, this attribute is written to

the cbscript.json file.
validvalues
If the value of the environment variable is to be selected from a
predefined list of values, include this parameter in the environment
variable configuration, and specify the valid values in a list. The
value specified by scriptdefaultvalue must be one of these valid
values.
Example:
"validvalues": ["a", "b", "c"],

If you specify this attribute, the list of valid values cannot be

empty. For example, the following statement is not valid:
"validvalues": [],

When the script package is downloaded, this attribute is written to

the cbscript.json file.
Example:
"keys":
[
{
"scriptkey": "DATABASE_NAME",
"scriptvalue": "",
"scriptdefaultvalue": ""
},
{
"scriptkey": "DATABASE_PORT",
"scriptvalue": "",
"scriptdefaultvalue": "50000",
"type": "integer",
"required": "true",
"validvalues": ["50000", "50001", "50002"],
"locked": "false"
},
{
"scriptkey": "SSL_ENABLED_ON_PORT",
"scriptvalue": "",
"scriptdefaultvalue": "true",
"type": "boolean"
}
]

380

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The information in the following additional fields on the Script Packages pane is
not included in the cbscript.json file when the script package is downloaded:
v Current status
v Access granted to
v Comments

Configuring JSON object script keys for password protection

For security purposes, you can specify a type field in a JSON object script key
definition to indicate that the field is a password and that the value displayed in
the user interface should be obscured.

Overview
When you define script keys in your JSON object, you might need to specify a
script key as a password and ensure that the value for that field is obscured in the
user interface.
In this situation, you can define the script key and include a type field with a
value of password to indicate that this field is to be protected. The script key
format is similar to the following example:
{
"scriptkey": "DATABASE_PASSWORD",
"scriptvalue": "",
"scriptdefaultvalue": "",
"type": "password"
},

Example of a cbscript.json file with the "type":"password" parameter

specified
{
"name": "Create DB2 Data Source to a highly available DB2 Enterprise database cluster",
"version": "1.0.0",
"description": "This script package creates a JDBC Provider and Data Source for a
highly available DB2 Enterprise database cluster",
"command": "/bin/sh /tmp/createDB2DataSource/createDB2DataSource.sh",
"log": "${WAS_PROFILE_ROOT}/logs/wsadmin.traceout",
"location": "/tmp/createDB2DataSource",
"timeout": "0",
"commandargs": "",
"keys":
[
{
"scriptkey": "DATASOURCE_NAME",
"scriptvalue": "",
"scriptdefaultvalue": "SAMPLE"
},
{
"scriptkey": "DATASOURCE_JNDI_NAME",
"scriptvalue": "",
"scriptdefaultvalue": "SAMPLE"
},
{
"scriptkey": "DATABASE_NAME",
"scriptvalue": "",
"scriptdefaultvalue": "SAMPLE"
},
{
"scriptkey": "DATABASE_USERNAME",
"scriptvalue": "",
"scriptdefaultvalue": "db2inst1"
},
Chapter 7. Managing and deploying virtual patterns

381

{
"scriptkey": "DATABASE_PASSWORD",
"scriptvalue": "",
"scriptdefaultvalue": "",
"type": "password"
},
{
"scriptkey": "DATABASE_HOST",
"scriptvalue": "",
"scriptdefaultvalue": "${DB2_ESE_Primary.hostname}.${DB2_ESE_Primary.domain}"
},
{
"scriptkey": "DATABASE_PORT",
"scriptvalue": "",
"scriptdefaultvalue": "50000"
}
]
}

Specifying alternate credentials for script package execution

You can include two special environment variables in your script package to
provide an alternate set of user ID and password credentials to connect to virtual
machines and run script packages.

Overview
By default, when you run a script package on a deployed virtual machine, the
original administrator user ID and password (for Windows) or the SSH RSA-key
(for Linux) is used to connect to the virtual machine.
If, for security reasons, the administrator password is changed, or if the capability
for root SSH login is disabled, the connection to the virtual machine cannot be
completed and the script package fails to run successfully.
In this situation, you can add two special environment variables to your
cbscript.json object file to specify an alternate user ID and password to connect
to the virtual machine:
v REMOTE_EXEC_OS_USER
v REMOTE_EXEC_OS_PASSWORD
This alternate set of credentials must be a valid operating system user with
sufficient permission to connect remotely to the virtual machine and run the script.
Important: To specify a user ID that is a member of the local Administrators
group, you must first disable User Account Control (UAC) remote restrictions.
Used remotely, these users have no elevation potential and cannot perform
administrative tasks. However a domain user in the Administrators group will run
with a full administrator access token from remote, and UAC remote restrictions
are not in effect. For more information about disabling UAC remote restrictions,
see the related links.
You can add these environment variables to your script package definition, by
adding them directly to the cbscript.json object file or by adding them as new
environment variables in the Environment section of the Script Packages pane.
When you later add this script package to a virtual system pattern part, you can
configure the user ID and password values in the script package while editing the

382

IBM Cloud Orchestrator 2.4.0.2: User's Guide

pattern, or later when you deploy the pattern and run the script package on
demand.

Including variables in the cbscript.json object file

The following example shows these environment variables defined in the
cbscript.json object file:
"keys":[
{
"scriptkey": "REMOTE_EXEC_OS_USER",
"scriptvalue": "",
"scriptdefaultvalue": "",
"locked": "false",
"required": "false"
},
{
"scriptkey": "REMOTE_EXEC_OS_PASSWORD",
"scriptvalue": "",
"scriptdefaultvalue": "",
"type": "password",
"locked": "false",
"required": "false"
}
]

Note that the REMOTE_EXEC_OS_PASSWORD script key is specified as a password type

to ensure that the value for that field is obscured in the user interface.

Adding new environment variables by using the Script Packages pane

If you use the Script Packages pane to add these as new environment variables, be
aware that the required attribute is set to true by default, and the type attribute is
not automatically added to the REMOTE_EXEC_OS_PASSWORD script key definition. To
configure these attributes, you must download your compressed file and modify
the environment variable attributes in the cbscript.json object file, then upload
the compressed file again to the script package.

Configuring script packages by using the

extendedattributes.json object
Use a special JSON object, extendedattributes.json, to include additional
information that is needed to configure a script package that you add to the
catalog.

Overview
In addition to the cbscript.json file, which contains essential configuration
information for your script package, you can include several more attributes to
extend your script package configuration for several special situations. This
extended attribute information is stored in another special JSON object that is
named extendedattributes.json, and must be in the root directory of the
uploaded compressed file (in the same directory as the cbscript.json object).
The extendedattributes.json object contains configuration information for the
following attributes:

Chapter 7. Managing and deploying virtual patterns

383

envonly
Specifies whether script package parameter values are set only in the
environment, or if they are also written to the virtualimage.properties
file before the script package is run.
On Linux and AIX, this file is in /etc/virtualimage.properties. On
Windows, this file is in c:\windows\setup\ibm\virtualimage.properties.
For more information, see the subsequent section, Writing script package
parameters to virtualimage.properties on page 385.
savevars
Specifies whether changes made to script package parameter values are
persisted after deployment, and reapplied to subsequent runs of the script
package. For more information, see the subsequent section, Saving
configuration changes to run script packages after deployment on page
386.
product_license
Specifies license information for the script package. The following
attributes are available:
productid
The product ID associated with the license, as represented in the
license catalog. Example:
"productid": "5725L53"

licensetype
Defines the type of license. The following values are valid:
PerCore
This type of license charges users according to the number
of processor cores that are used.
PVU

This type of license charges users according to the

processor value units used.

SERVER This type of license charges users according to the number

of virtual servers used.
COMPUTE_NODE
This type of license charges users according to the number
of compute nodes that are used.
Example:
"licensetype": "PVU"

licensecpu
When the type of license is SERVER, this required attribute
specifies the processor count limit for this server license. Example:
"licensecpu": "4"

licensememory
When the type of license is SERVER, this required attribute
specifies the memory limit in GB for this server license. Example:
"licensememory": "4"

Note: After you upload a script package, refresh the Script Packages page to
display the uploaded information from the JSON object in the console.

384

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Writing script package parameters to virtualimage.properties

By default, before a script package is run in your virtual machine environment, the
script package parameters are written to the virtualimage.properties file. If you
later want to manually run the script again, you must source the
virtualimage.properties file to repopulate your environment with the parameters
that the script needs to run successfully.
On Linux and AIX, this file is in /etc/virtualimage.properties. On Windows, this
file is in c:\windows\setup\ibm\virtualimage.properties.
This is not considered to be a best practice. In general, environment properties that
are written to the virtualimage.properties file should be only those properties
that are defined or provided by the virtual image. Design your script packages
such that they do not depend on these parameters being available in this file.
For scripts that are run during deployment, or for scripts that run on demand from
the console, all script package variables are set and available in the environment
before the script is run. This includes variables that are defined in
virtualimage.properties. So in these cases there is no need to source this file.
There might be other situations, however, when you do not want the script
package parameters to be written to the virtualimage.properties file. For
example, if your script package parameters include password parameters, such as
parameters that contain the text string password in their name, or parameters
whose type is password, the values for these password parameters are written to
virtualimage.properties in clear text, which might be a security concern in your
environment.
In most situations, prevent script package parameters from being written to
virtualimage.properties by including the envonly (environment only) attribute in
the extendedattributes.json file in your script package.
The following values are valid for this attribute:
true

Script package parameter values are set only in the environment and are
not written to the virtualimage.properties file. This setting is the
preferred setting.

false

Script package parameter values are set in the environment and are written
to the virtualimage.properties file. This value is the default value. If this
file is not included in your script package, the default value of false is
assumed.

In the extendedattributes.json file, define the envonly parameter as follows here:

{
"envonly": "true"
}

In general, your script packages should not need to access parameters from the
virtualimage.properties file. If you must run scripts manually in your
environment, save these parameters in your own file instead.
Important: When a script package executes, its environment variables, if any, are
added to the environment, along with any environment variables from previously

Chapter 7. Managing and deploying virtual patterns

385

executed script packages. These environment variables are then written out to the
virtualimage.properties file or not, based on the value of the envonly setting for
that script package.
This means that if one script package runs with envonly set to true, followed by a
second script package that runs with envonly set to false (the default), the
environment variables for the second script package are written to
virtualimage.properties, including the environmental variables from the first
script package.
If your pattern deployment is running multiple script packages, and all have
envonly set to true, environment variables are still written to the
virtualimage.properties file, however script package variables are not. However,
if one or more scripts have envonly set to false (or if envonly is not specified),
then the virtualimage.properties file contains the variables from all of the script
packages that have run up to this point.

Saving configuration changes to run script packages after

deployment
Script packages are created and customized with environment variables and added
to the catalog, where they can be selected and included in a virtual system pattern.
When that virtual system pattern is deployed, one or more virtual machines are
created in the environment.
For each virtual machine, an initial copy of the script package parameters is
defined, by using the configuration that is passed in by the environment variables.
Then, for each instance of the virtual machine, another copy of the script package
parameters, unique for that virtual machine instance, is defined.
For any virtual machine instance, each subsequent time that you run the script
package, the same values for the environment variables that were in effect at the
time of deployment are presented again. Any changes that you want to apply to
these variables must be made manually each time the script package is run.
If, after deployment, you return to the Script Packages catalog page and modify
the configuration of the environment variables in the script package, those changes
are not applied to deployed instances of that script package on subsequent
executions. The configuration that was in effect at the time of deployment are
presented instead.
You might have a situation in which you anticipate needing to change the
configuration of a script package after it is deployed, and then apply those changes
each subsequent time when the script package is run again. For example, you
might configure and deploy a virtual system pattern with a script package that
provides encryption support. Later, you update the encryption configuration to
add a path to encrypt on a virtual machine, and you want that change to be
applied each time that you run the script again on all the instances of that virtual
machine.
In this situation, in your script package configuration in the Script Packages page,
select Yes in the Save environment variables after post-deployment executions
field to indicate that when you update script parameters on the deployed script
package, those changes are to be saved after execution and applied to subsequent
executions of the script.

386

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This value is stored in the extendedattributes.json file in the savevars attribute.

The following values are valid for this attribute:
1

An integer value equivalent to Yes (as configured in the Script Packages

page), indicating that changes made to script package parameter values
after deployment are persisted. On subsequent runs of the script package,
the most recent updates to script package parameter values are used
instead of the configuration that was in effect at the time of deployment.
This setting affects all instances of the script. Each usage of the script in a
deployment pattern has its own copy of the script parameter values.

An integer value equivalent to No (as configured in the Script Packages

page), indicating that changes made to script package parameter values
after deployment are not persisted. On subsequent runs of the script
package, the parameter values that were applied at the time of deployment
are presented, and you must manually change these values as needed each
time that you run the script package.

In the extendedattributes.json file, the savevars attribute is formatted as follows:

{
"savevars": "1"
}

Example of attributes in the extendedattributes.json object

The basic syntax for parameters that are specified in the extendedattributes.json
object is of the form:
"<parameter_name>": "<parameter_value>"

Example:
[
{
"envonly": "true",
"savevars": "1",
"product_license": {
"productid": "5725A26",
"licensetype": "SERVER",
"licensecpu": "16",
"licensememory": "4"
}
}
]

Example of using the savevars attribute

Consider an example of a deployed pattern that creates a single virtual machine,
VMa, with an initial script package configuration, PCa. Suppose that the virtual
machine has two instances, VMa1 and VMa2, and both are defined to run the
script package.
v Each virtual machine instance that is created runs the script by using a unique
copy of PCa.
Instance VMa1 has configuration PCa1.
Instance VMa2 has configuration PCa2.
v When the script package is run on either of these virtual machine instances, the
equivalent configuration at the time of deployment is applied, since PCa is
identical to PCa1 and PCa2.

Chapter 7. Managing and deploying virtual patterns

387

v Now, suppose you run the script package on instance VMa1 and change the
configuration settings, effectively creating a new set of parameters, PCa3.
v With the savevars attribute set to 1 (Yes), the configuration PCa3 is saved,
replacing both PCa1 for VMa1 and PCa for the virtual machine:
Virtual machine VMa now has the latest configuration settings, PCa3.
Instance VMa1 also has the latest configuration settings, PCa3.
Instance VMa2 still has its copy of the original configuration, PCa2.
v When the script is run subsequent times on VMa1, PCa3 is applied.
v The next time that the script is run on VMa2, however, PCa2 is applied, but after
execution completes, PCa2 is replaced by the latest configuration, PCa3. On
subsequent runs of the script on VMa2, PCa3 is applied:
Virtual machine VMa has the latest configuration settings, PCa3.
Instance VMa1 has the latest configuration settings, PCa3.
Instance VMa2 now has the latest configuration settings, PCa3.

Script package environment variables

When you are defining a script package to IBM Cloud Orchestrator, you can refer
to environment variables that are provided by the system, as well as custom
environment variables that you define in your script package.

Purpose of environment variables

You can use the environment variables provided by IBM Cloud Orchestrator, in
addition to customized environment variables that you define, in your script
packages. The set of environment variables that are provided is determined by
what environment variables exist on the virtual machine.
Environment variables that are available with the system are provided through the
virtual image and after deployment are located in the virtualimage.properties file
on each virtual machine.
On Linux and AIX, this file is located in /etc/virtualimage.properties. On
Windows, this file is located in c:\windows\setup\ibm\virtualimage.properties.
Script package environment variables that you define might or might not also be
located in the virtualimage.properties file, depending on your configuration
settings. As a best practice, if you must run your scripts manually, you should
avoid depending on script package variables being available in the
virtualimage.properties file, and design your script package to save properties in
your own file as needed. See the related links for configuring script packages using
the extendedattributes.json object for more information about controlling
whether or not script package parameters are stored in this file.
You can include these environment variables in your script packages by using any
of the following methods:
v In the cbscript.json file of your compressed script file, you can define
customized environment variables that are populated in the Environment field
of the Script Packages window when the compressed file is uploaded into IBM
Cloud Orchestrator.
v In the user interface, specify the environment variables in the Environment field
of the Script Packages window.

388

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Life cycle variables

A set of life cycle variables is included with most virtual images. These
environment variables specify many of the scripts and locations required to
manage the life cycle of the virtual system instances:
Install service
SERVICE_COMMAND_LOCATION="/var/adm/virtualimages/bin"
Install service
SERVICE_COMMAND="installService.sh"
Install service
SERVICE_PACKAGE_LOCATION="/tmp/update"
Install service
OS_SERVICE_PACKAGE_LOCATION="/tmp/update/os"
Install service
APP_SERVICE_PACKAGE_LOCATION="/tmp/update/app"
Reset virtual image
RESET_VIRTUAL_IMAGE_COMMAND_LOCATION="/var/adm/
ibmvmcoc-postinstall"
Reset virtual image
RESET_VIRTUAL_IMAGE_COMMAND="resetvm.sh"
Start virtual image services
START_SERVICES_COMMAND_LOCATION="/var/adm/virtualimages/
bin"
Start virtual image services
START_SERVICES_COMMAND="startVirtualImageService.sh"
Stop virtual image services
STOP_SERVICES_COMMAND_LOCATION="/var/adm/virtualimages/
bin"
Stop virtual image services
STOP_SERVICES_COMMAND="stopVirtualImageService.sh"

WebSphere Application Server variables

The following variables can be used for IBM WebSphere Application Server
Hypervisor Edition virtual images:
Number of Profiles to create (AdminAgent)
PROFILE_NUMBER=
Autostart WebSphere Servers
AUTOSTART=true
Federate Node (true | false)
DMGR_FEDERATE=false
Register with Job Manager (true | false)
JMGR_REGISTER=false
WebSphere Application Server operation commands to use for start and stop
services commands
OPERATION_COMMAND_LOCATION="/opt/IBM/AE/AS"

Chapter 7. Managing and deploying virtual patterns

389

WebSphere Application Server operation commands to use for start and stop
services commands
OPERATION_COMMAND="${WAS_PROFILE_ROOT}/bin/ws_ant.sh -f
/opt/IBM/AE/AS/wasHVControl.ant"
WebSphere Administrative Console URL
ADMIN_CONSOLE_URL=
WebSphere Cell Name
CELL_NAME=RainmakerCell0
WebSphere Default Profile location
WAS_PROFILE_ROOT=/opt/IBM/WebSphere/Profiles/DefaultAppSrv01
WebSphere Default Install Location
WAS_INSTALL_ROOT=/opt/IBM/WebSphere/AppServer
WebSphere Profile Root
PROFILE_ROOT=/opt/IBM/WebSphere/Profiles
WebSphere Hostname
HOSTNAME=vm-009-097.rainmaker.raleigh.ibm.com
WebSphere Node Name
NODE_NAME=RainmakerNode0
WebSphere Profile Name
PROFILE_NAME=DefaultAppSrv01
WebSphere Profile Type
PROFILE_TYPE=default
The following additional variables are dynamic. IBM Cloud Orchestrator adds
them each time a script requiring them is run. After the script has completed, these
environment variables are removed.
WebSphere Administrative Password
WAS_PASSWORD=password
WebSphere Administrative Username
WAS_USERNAME=virtuser

Properties variable syntax

A properties variable syntax, ${...}, is used for variables in script packages that
are not known until deployment time.
Certain values, such as host names, are not always known before deployment. In
IBM Cloud Orchestrator you can still reference these properties in your script
package by using a certain syntax. This format can be used when associating the
script with a part or it can be used when the pattern is deployed.
The general syntax for these variables is ${part-name_.property-name}. Each part
has a unique name that is not translated that can be used like a variable. You can
find this unique part name by clicking the properties icon of the part. The value in
the Name field is the value that can be used as the part-name. When a part name
contains spaces, such as Core OS, the syntax does support the use of the space
character.
The property name can be any properties you have added to your script package.
For example, if you have a part named DMGRPart and have an associated script that
has a property called MYPROPERTY, you can use ${DMGRPart_.MYPROPERTY} to

390

IBM Cloud Orchestrator 2.4.0.2: User's Guide

represent that future value of that property. In addition to custom properties, the
property name can also be any of the following built-in values:
Network-oriented variables
v hostname
v domain
v
v
v
v
v

ipaddr
netmask
gateway
pri_dns
sec_dns

Note: If you want to set the hostname variable for the Windows system,
consider the limitation described in Setting the host name when
deploying a Windows system on page 1039
Locale-oriented variables
v language
v country
v encoding
WebSphere Application Server-oriented variables
v cell_name
v node_name
v augment_list
Related tasks:
Associating a script package with a pattern on page 371
You can associate a script package with a pattern and defined cell through the user
interface.
Working with virtual system patterns (classic) on page 434
Using a virtual system pattern, you can describe the topology of a system that you
want to deploy. Virtual system patterns provide repeatable system deployment that
can be reproduced. To build virtual system patterns, you can use parts from one or
more virtual images, add-ons, and script packages.

Script package examples

A number of example script packages are provided with the system. Additional
examples of typical script packages are described.

Script packages provided with the system

The following script packages are included with the system in the catalog:
v Add an IBM HTTP Server node
v Disable Root Login
v Vertical CPU Scaling
v Vertical Memory Scaling
In addition to these script packages, there are several sample compressed archive
files provided with the Plug-in Development Kit that you can use as examples for
creating your own script packages to provide vertical scaling of CPU and memory
resources for middleware.

Chapter 7. Managing and deploying virtual patterns

391

Add an IBM HTTP Server node

The Add an IBM HTTP Server node script package is a special script package that
contains no code and no executable script. It contains only a single environment
variable, ihs = true. This script package is valid for use only with classic virtual
system patterns.
You can add this script package only to deployment manager parts or standalone
server parts. The configuration of the IBM HTTP Server is part of the provisioning
of the deployment manager or standalone server parts. Adding this script package
indicates to these two parts that the IBM HTTP Server should be configured. When
you add this script package to a deployment manager part, for example, you will
see one web server in the Web Servers list (with Web Server Type=IBM HTTP
Server).
If you add this script package to a different part type, for example, a custom node
or an on demand router node, no action is taken. In these cases, an IBM HTTP
Server configuration is not processed, because if, for example, more than one
custom node is deployed, there would be an IBM HTTP Server on every custom
node. This is not the intent of the pattern.

Disable Root Login

You can add this script package to a pattern deploying a virtual Linux system. The
script disables SSH login by the root user. You can also modify the script package
to run on demand, and add this script package at a later time to disable the root
login as needed.
Note: IBM Cloud Orchestrator must be able to log in to the virtual machine as root
to run script packages and perform other management functions. IBM Cloud
Orchestrator automatically generates a public/private key pair during deployment;
it then uses the private key to log in to the virtual machine as root to run script
packages. This script modifies the operating system configuration to allow remote
root login only with this predefined private key.
When this script package is deployed with the image, it makes changes to the
operating system configuration. For more information about these changes, see the
related links.
The archive file for this script package is named disableRootLogin.zip. It contains
the following files:
cbscript.json
This file contains the following parameter information:
[
{
"command": "\/tmp\/disableRootLogin\/disableRootLogin.sh",
"description": "Disables Root Login for AIX and Linux",
"execmode": 0,
"filename": "disableRootLogin.zip",
"location": "\/tmp\/disableRootLogin\/",
"log": "\/tmp\/disableRootLogin\/logs",
"name": "Disable Root Login",
"ostype": "linux\/unix",
"timeout": 0,
"type": "APPLICATION"
}
]

392

IBM Cloud Orchestrator 2.4.0.2: User's Guide

To modify the script package to run manually, change the value of

execmode to 2.
extendedattributes.json
This file contains the following parameter information:
[
{
"savevars": "0"
}
]

The savevars parameter controls whether environment variables are saved

after post-deployment executions. A value of 0 indicates that variables are
not saved.
disableRootLogin.sh
This is the script that is called when the script package is run.
README.TXT
Some basic information is included in this file.

Vertical CPU Scaling

This is a generic scaling policy that uses operating system metrics to scale the
number of vCPUs that are allocated to a virtual machine. You can add this script
package to a pattern deploying a virtual Linux system.
You can use this as a starting point to define your own scaling policy, and you can
add the resulting script package to any supported virtual system part. When this
scaling policy is deployed, a monitoring and auto-scaling agent runs in each
virtual machine to trigger scaling independent of other nodes.
The archive file for this script package is named VerticalScaleGenericCPU.zip. It
contains the following files:
cbscript.json
This file contains the following parameter information:
[
{
"command": "\/tmp\/VerticalScaleGenericCPU\/enable_as.sh",
"description": "A generic scaling policy that uses operating system metrics
to scale the number of vCPUs allocated to a virtual machine.",
"execmode": 0,
"filename": "VerticalScaleGenericCPU.zip",
"keys": [
{
"locked": false,
"required": true,
"scriptdefaultvalue": "1",
"scriptkey": "MIN_CPU_COUNT"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "8",
"scriptkey": "MAX_CPU_COUNT"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "80",
"scriptkey": "SCALE_UP_CPU_THRESHOLD"
Chapter 7. Managing and deploying virtual patterns

393

},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "0",
"scriptkey": "SCALE_DOWN_CPU_THRESHOLD"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "300",
"scriptkey": "TRIGGER_TIME"
}
],
"location": "\/tmp\/VerticalScaleGenericCPU",
"log": "\/tmp\/VerticalScaleGenericCPU",
"name": "VerticalScaleGenericCPU",
"ostype": "linux\/unix",
"timeout": 0,
"type": "APPLICATION"
}
]

The following environment variables are defined:

MIN_CPU_COUNT
This is a required variable that indicates the minimum number of
vCPUs that the virtual machine must have. The default value is 1.
MAX_CPU_COUNT
This is a required variable that indicates the maximum number of
vCPUs to which the virtual machine can be scaled. The default
value is 8.
SCALE_UP_CPU_THRESHOLD
This is a required variable that indicates the percent threshold of
CPU usage that, when exceeded, triggers a scale up operation to be
automatically performed on the virtual machine. This threshold
must be exceeded for the duration of time indicated by the
TRIGGER_TIME variable before scaling is performed. The default
value is 80 percent.
SCALE_DOWN_CPU_THRESHOLD
This variable is set to 0 percent by default. Scaling down is not
supported for IBM Cloud Orchestrator.
TRIGGER_TIME
This is a required variable that indicates the time, in seconds, that
a threshold must be exceeded before a scaling operation is
performed. The default value is 300 seconds. For example, if the
CPU usage on a virtual machine exceeds the
SCALE_UP_CPU_THRESHOLD value (80%) for 300 seconds (5 minutes),
then a scale up operation is triggered to increase the vCPU count.
extendedattributes.json
This file contains the following parameter information:
[
{
"savevars": "0"
}
]

394

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The savevars parameter controls whether environment variables are saved

after post-deployment executions. A value of 0 indicates that variables are
not saved.
enable_as.sh
This is the script that is called when the script package is run.
When you deploy a virtual system pattern that uses this script package, the
deployment history (over time) shows when the number of CPUs is changed. A
message is displayed, similar to the following example:
CPU changed for virtual machine auslpas165-OS Node-scalingCPUTest-766
from 2 cores to 3 cores

For each vertical scaling operation, the number of vCPUs is increased by one CPU.

Vertical Memory Scaling

This is a generic scaling policy that uses operating system metrics to scale the
amount of memory that is allocated to a virtual machine. You can add this script
package to a pattern deploying a virtual Linux system.
You can use this as a starting point to define your own scaling policy, and you can
add the resulting script package to any supported virtual system part. When this
scaling policy is deployed, a monitoring and auto-scaling agent runs in each
virtual machine to trigger scaling independent of other nodes.
The archive file for this script package is named VerticalScaleGenericMemory.zip.
It contains the following files:
cbscript.json
This file contains the following parameter information:
[
{
"command": "\/tmp\/VerticalScaleGenericMemory\/enable_as.sh",
"description": "A generic scaling policy that uses operating system metrics
to scale the amount of memory allocated to a virtual machine.",
"execmode": 0,
"filename": "VerticalScaleGenericMemory.zip",
"keys": [
{
"locked": false,
"required": true,
"scriptdefaultvalue": "4096",
"scriptkey": "MIN_MEMORY"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "8192",
"scriptkey": "MAX_MEMORY"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "80",
"scriptkey": "SCALE_UP_MEMORY_THRESHOLD"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "0",
"scriptkey": "SCALE_DOWN_MEMORY_THRESHOLD"
Chapter 7. Managing and deploying virtual patterns

395

},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "300",
"scriptkey": "TRIGGER_TIME"
}
],
"location": "\/tmp\/VerticalScaleGenericMemory",
"log": "\/tmp\/VerticalScaleGenericMemory",
"name": "VerticalScaleGenericMemory",
"ostype": "linux\/unix",
"timeout": 0,
"type": "APPLICATION"
}
]

The following environment variables are defined:

MIN_MEMORY
This is a required variable that indicates the minimum amount of
memory that the virtual machine must have. The default value is
4096.
MAX_MEMORY
This is a required variable that indicates the maximum amount of
memory to which the virtual machine can be scaled. The default
value is 8192.
SCALE_UP_MEMORY_THRESHOLD
This is a required variable that indicates the percent threshold of
memory usage that, when exceeded, triggers a scale up operation
to be automatically performed on the virtual machine. This
threshold must be exceeded for the duration of time indicated by
the TRIGGER_TIME variable before scaling is performed. The default
value is 80 percent.
SCALE_DOWN_MEMORY_THRESHOLD
This variable is set to 0 percent by default. Scaling down is not
supported for IBM Cloud Orchestrator.
TRIGGER_TIME
This is a required variable that indicates the time, in seconds, that
a threshold must be exceeded before a scaling operation is
performed. The default value is 300 seconds. For example, if the
memory usage on a virtual machine exceeds the
SCALE_UP_MEMORY_THRESHOLD value (80%) for 300 seconds (5
minutes), then a scale up operation is triggered to increase the
amount of memory allocated to the virtual machine.
extendedattributes.json
This file contains the following parameter information:
[
{
"savevars": "0"
}
]

The savevars parameter controls whether environment variables are saved

after post-deployment executions. A value of 0 indicates that variables are
not saved.

396

IBM Cloud Orchestrator 2.4.0.2: User's Guide

enable_as.sh
This is the script that is called when the script package is run.
When you deploy a virtual system pattern that uses this script package, the
deployment history (over time) shows when the amount of memory is changed. A
message is displayed, similar to the following example:
Memory changed for virtual machine auslpas158-Standalone from 2048 to 3072

For each vertical scaling operation, the amount of memory is increased by 1024
MB.

Vertical scaling of CPU for WebSphere Application Server

Hypervisor Edition
In addition to the generic script package that you can use for vertical scaling of
CPU in your virtual machines, you can create your own script packages that you
can use for vertical scaling of CPU for middleware components such as WebSphere
Application Server, DB2, and others.
Typically if you need to tune your middleware configuration after a scaling
operation to take advantage of the availability of additional resources, you might
need to provide your own content specific resource.py executable. The scaling
function will locate and run this file to adjust middleware as needed based on the
resource changes. For example, after performing a CPU scaling operation for
WebSphere Application Server Hypervisor Edition, you might need to increase the
thread pool size to take advantage of the additional vCPU resource.
A sample compressed archive file, WASHV_CPUBased.zip, is included in the Plug-in
Development Kit, as an example for creating a vertical scaling script package for
WebSphere Application Server Hypervisor Edition. See the related links for more
information about downloading and unpacking the Plug-in Development Kit.
Use the standard procedure for creating a script package in the IBM Cloud
Orchestrator catalog, and upload this archive file into the script package. The
archive file contains the following files:
cbscript.json
This file contains the following parameter information:
[
{
"command": "\/bin\/sh \/tmp\/WASHV_CPUBased\/enable_as.sh",
"description": "A WASHV script example for scaling up based CPU",
"execmode": 0,
"filename": "WASHV_CPUBased.zip",
"keys": [
{
"locked": false,
"required": true,
"scriptdefaultvalue": "1",
"scriptkey": "MIN_CPU_COUNT",
"scriptvalue": "1"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "8",
"scriptkey": "MAX_CPU_COUNT",
"scriptvalue": "8"
},
{
Chapter 7. Managing and deploying virtual patterns

397

"locked": false,
"required": true,
"scriptdefaultvalue": "80",
"scriptkey": "SCALE_UP_CPU_THRESHOLD",
"scriptvalue": "80"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "0",
"scriptkey": "SCALE_DOWN_CPU_THRESHOLD",
"scriptvalue": "0"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "120",
"scriptkey": "TRIGGER_TIME",
"scriptvalue": "120"
}
],
"location": "\/tmp\/WASHV_CPUBased",
"log": "\/tmp\/WASHV_CPUBased",
"name": "WAS_VerticalScalingCPUScriptPkg",
"ostype": "linux\/unix",
"timeout": 0,
"type": "APPLICATION"
}
]

The following environment variables are defined:

MIN_CPU_COUNT
This is a required variable that indicates the minimum number of
vCPUs that the virtual machine must have. The default value is 1.
MAX_CPU_COUNT
This is a required variable that indicates the maximum number of
vCPUs to which the virtual machine can be scaled. The default
value is 8.
SCALE_UP_CPU_THRESHOLD
This is a required variable that indicates the percent threshold of
CPU usage that, when exceeded, triggers a scale up operation to be
automatically performed on the virtual machine. This threshold
must be exceeded for the duration of time indicated by the
TRIGGER_TIME variable before scaling is performed. The default
value is 80 percent.
SCALE_DOWN_CPU_THRESHOLD
This variable is set to 0 percent by default. Scaling down is not
supported for IBM Cloud Orchestrator.
TRIGGER_TIME
This is a required variable that indicates the time, in seconds, that
a threshold must be exceeded before a scaling operation is
performed. The default value is 120 seconds. For example, if the
CPU usage on a virtual machine exceeds the
SCALE_UP_CPU_THRESHOLD value (80%) for 120 seconds (2 minutes),
then a scale up operation is triggered to increase the vCPU count.
extendedattributes.json
This file contains the following parameter information:

398

IBM Cloud Orchestrator 2.4.0.2: User's Guide

[
{
"savevars": "0"
}
]

The savevars parameter controls whether environment variables are saved

after post-deployment executions. A value of 0 indicates that variables are
not saved.
enable_as.sh
This is the script that is called when the script package is run.
resource.py
This is the script that is run automatically to perform the middleware
tuning to take advantage of the change in CPU resource. In this example,
the scripts/was_web_thread.py script is called, which adjusts the thread
pool size for WebSphere Application Server.
The script contains the following code:
import sys
import subprocess
import json
parms = json.loads(sys.argv[1])
if int(parms[newCpuCount]) > int(parms[oldCpuCount]):
cpu = parms[newCpuCount]
retcode = subprocess.call([sh, /opt/IBM/WebSphere/AppServer/bin/wsadmin.sh,
-lang, jython, -f, /tmp/WASHV_CPUBased/scripts/was_web_thread.py,
str(cpu)])
print wsadmin.sh return code:, retcode

was_webresource.py
This script is located in the scripts folder, and is called by resource.py to
perform the middleware tuning to adjust the thread pool size for
WebSphere Application Server.
The script contains the following code:
import AdminUtilities
def getName(objectId):
endIndex = (objectId.find("(c") - 1)
stIndex = 0
if (objectId.find("\"") == 0):
stIndex = 1
return objectId[stIndex:endIndex+1]
assert len(sys.argv) == 1
target_cpu = int(sys.argv[0])
setMaxInt = 20 * target_cpu
setMaxStr = str(setMaxInt)
print "Set WebContainers thread pool max size: %s, min size: %s" %
(setMaxStr, setMaxStr)
try:
theList = AdminControl.completeObjectName(
WebSphere:*,type=ThreadPool,name=WebContainer)
theList = theList.splitlines()
for tp in theList:
if tp.find(WebContainer) != -1:
currMinSize = AdminControl.invoke(tp, getMinimumPoolSize)
currMinSize = int(currMinSize)
currMaxSize = AdminControl.invoke(tp, getMaximumPoolSize)
currMaxSize = int(currMaxSize)

Chapter 7. Managing and deploying virtual patterns

399

if currMaxSize < setMaxInt:

print "currMaxSize is %s" % currMaxSize
print "new MaxSize is %s" % setMaxStr
AdminControl.setAttributes(tp, [[maximumSize, setMaxStr],
[minimumSize, setMaxStr]])
except:
print "WAS process is not running, only update the config file"
server1 = AdminConfig.getid(/Cell:CloudBurstCell_1/Node:CloudBurstNode_1/Server:server1/)
tpList = AdminConfig.list(ThreadPool, server1)
for pool in tpList.split("\n"):
pool = pool.rstrip()
if (getName(pool) == "WebContainer"):
attrs = [["maximumSize", setMaxInt], ["minimumSize", setMaxInt]]
AdminConfig.modify(pool, attrs)
AdminConfig.save()
break

Vertical scaling of memory for WebSphere Application Server

Hypervisor Edition
In addition to the generic script package that you can use for vertical scaling of
memory in your virtual machines, you can create your own script packages that
you can use for vertical scaling of memory for middleware components such as
WebSphere Application Server, DB2, and others.
Typically if you need to tune your middleware configuration after a scaling
operation to take advantage of the availability of additional resources, you might
need to provide your own content specific resource.py executable. The scaling
function will locate and run this file to adjust middleware as needed based on the
resource changes. For example, after performing a memory scaling operation for
WebSphere Application Server Hypervisor Edition, you might need to adjust the
JVM heap size to take advantage of the additional memory resource.
A sample compressed archive file, WASHV_MemoryBased.zip, is included in the
Plug-in Development Kit, as an example for creating a vertical scaling script
package for WebSphere Application Server Hypervisor Edition. See the related
links for more information about downloading and unpacking the Plug-in
Development Kit.
Use the standard procedure for creating a script package in the IBM Cloud
Orchestrator catalog, and upload this archive file into the script package. The
archive file contains the following files:
cbscript.json
This file contains the following parameter information:
[
{
"command": "\/bin\/sh \/tmp\/WASHV_MemoryBased\/enable_as.sh",
"description": "A WASHV script example for scaling up based Memory",
"execmode": 0,
"filename": "WASHV_MemoryBased.zip",
"keys": [
{
"locked": false,
"required": true,
"scriptdefaultvalue": "1024",
"scriptkey": "MIN_MEMORY",
"scriptvalue": "1024"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "4096",

400

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"scriptkey": "MAX_MEMORY",
"scriptvalue": "4096"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "80",
"scriptkey": "SCALE_UP_MEMORY_THRESHOLD",
"scriptvalue": "80"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "0",
"scriptkey": "SCALE_DOWN_MEMORY_THRESHOLD",
"scriptvalue": "0"
},
{
"locked": false,
"required": true,
"scriptdefaultvalue": "120",
"scriptkey": "TRIGGER_TIME",
"scriptvalue": "120"
}
],
"location": "\/tmp\/WASHV_MemoryBased",
"log": "\/tmp\/WASHV_MemoryBased",
"name": "WAS_VerticalScalingMemoryScriptPkg",
"ostype": "linux\/unix",
"timeout": 0,
"type": "APPLICATION"
}
]

The following environment variables are defined:

MIN_MEMORY
This is a required variable that indicates the minimum amount of
memory that the virtual machine must have. The default value is
1024.
MAX_MEMORY
This is a required variable that indicates the maximum amount of
memory to which the virtual machine can be scaled. The default
value is 4096.
SCALE_UP_MEMORY_THRESHOLD
This is a required variable that indicates the percent threshold of
memory usage that, when exceeded, triggers a scale up operation
to be automatically performed on the virtual machine. This
threshold must be exceeded for the duration of time indicated by
the TRIGGER_TIME variable before scaling is performed. The default
value is 80 percent.
SCALE_DOWN_MEMORY_THRESHOLD
This variable is set to 0 percent by default. Scaling down is not
supported for IBM Cloud Orchestrator.
TRIGGER_TIME
This is a required variable that indicates the time, in seconds, that
a threshold must be exceeded before a scaling operation is
performed. The default value is 120 seconds. For example, if the
memory usage on a virtual machine exceeds the
SCALE_UP_MEMORY_THRESHOLD value (80%) for 120 seconds (2
Chapter 7. Managing and deploying virtual patterns

401

minutes), then a scale up operation is triggered to increase the

amount of memory allocated to the virtual machine.
extendedattributes.json
This file contains the following parameter information:
[
{
"savevars": "0"
}
]

The savevars parameter controls whether environment variables are saved

after post-deployment executions. A value of 0 indicates that variables are
not saved.
enable_as.sh
This is the script that is called when the script package is run.
resource.py
This is the script that is run automatically to perform the middleware
tuning to take advantage of the change in memory resource. In this
example, the script calculates the adjustment needed to the heap size, then
calls the scripts/stopServer.py script to stop the WebSphere Application
Server, then issues the command to start the server again. The WebSphere
process must be restarted for the new JVM heap configuration to take
effect.
The script contains the following code:
import
import
import
import
import
import
import
import

os
sys
json
re
shutil
commands
logging
subprocess

def calculate_64bit_jvmmemory(matchobj):
newHeapSize = int(matchobj.group(1)) + int(gap/1.5/128)*128
if newHeapSize > 6144:
return 6144
else :
return str(newHeapSize)
def calculate_32bit_jvmmemory(matchobj):
newHeapSize = int(matchobj.group(1)) + int(gap/1.5/128)*128
if newHeapSize > 2048:
return 2048
else :
return str(newHeapSize)
def jvm_memory_str(matchobj):
newHeapSize = int(int(parms[newMemory])/1.5/128)*128
if newHeapSize > 2048:
newHeapSize = 2048
strval = str(matchobj.group(1)) + initialHeapSize="128" maximumHeapSize="
+str(newHeapSize)+"
return str(strval)
def startServer():
#os.system(/opt/IBM/WebSphere/AppServer/bin/startServer.sh server1)
subprocess.call([sh, /opt/IBM/WebSphere/AppServer/bin/startServer.sh,
server1])
logger.debug("start Server...")
def stopServer():
#os.system(/opt/IBM/WebSphere/AppServer/bin/stopServer.sh server1)
command = /opt/IBM/WebSphere/AppServer/bin/wsadmin.sh -conntype SOAP
-lang jython -f /tmp/WASHV_MemoryBased/scripts/stopServer.py
subprocess.call(command, shell=True)

402

IBM Cloud Orchestrator 2.4.0.2: User's Guide

logger.debug("stop Server...")
logger = logging.getLogger("resource.py")
parms = json.loads(sys.argv[1])
if int(parms[newMemory]) > int(parms[oldMemory]):
gap = int(parms[newMemory]) - int(parms[oldMemory])
#originalFile =
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/localhostNode01Cell
/nodes/localhostNode01/servers/server1/server.xml
originalFile =
/opt/IBM/WebSphere/Profiles/DefaultAppSrv01/config/cells/CloudBurstCell_1
/nodes/CloudBurstNode_1/servers/server1/server.xml
backupFile = originalFile + .bk
output = commands.getoutput(/opt/IBM/WebSphere/AppServer/bin/versionInfo.sh)
#print output
if os.path.exists(originalFile):
if not os.path.exists(backupFile):
shutil.copy(originalFile, backupFile)
with open(originalFile) as cfgFile :
data = cfgFile.read()
m = re.search(32 bit,output)
n = re.search(64 bit,output)
if m :
print IBM 32-bit SDK for Java
t = re.search(maximumHeapSize=,data)
if t :
if re.search(maximumHeapSize="2048",data):
print maximumHeapSize="2048" There is no extra
memory size to scaling up
logger.debug("There is no extra memory size to scaling up")
new_data = data
else :
new_data=re.sub(r(?<=maximumHeapSize=")
(\d+), calculate_32bit_jvmmemory, data)
else :
new_data=re.sub(r(?<=verboseModeJNI=")(\S+), jvm_memory_str, data)
elif n :
print IBM 64-bit SDK for Java
new_data=re.sub(r(?<=maximumHeapSize=")
(\d+), calculate_64bit_jvmmemory, data)
else :
print Nothing changed...
logger.debug("There is no related information ")
if cmp(data,new_data) != 0 :
with open(originalFile, "w") as cfgFile :
cfgFile.write(new_data)
Info = commands.getoutput(ps -ef | grep java)
res = re.search(server1,Info)
if res :
print stopServer ....
stopServer()
print startServer ....
startServer()
else :
print startServer ....
startServer()
else :
logger.debug("There is no configuration file to update ")

stopServer.py
This script is located in the scripts folder, and is called by resource.py to
stop the WebSphere Application Server instance.
The script contains the following code:
AdminControl.stopServer("server1", "CloudBurstNode_1")

Additional example script packages

In addition to the script packages provided with the system, you can review the
following examples that demonstrate how script packages are used in a virtual
Chapter 7. Managing and deploying virtual patterns

403

system environment.

Example script package to install an application

This script installs an existing application in a user-specified location. The location
can be either on the file system, or at some remote location. The wsadmin tool
installs the application. You can pass in installation arguments during deployment.

Script variables
There are two parameters that are part of this script package.
APP_LOCATION:
Required. The location of the application. The location of the application
can be either a file system location or remote location over http or https.
INSTALL_ARGS:
Optional. Install arguments for the AdminApp.install() wsadmin command.
The default command is "AdminApp.install(appLocation,
'[-usedefaultbindings]'). Other arguments can be supplied using this
variable. An example value for this variable is "-usedefaultbinding
-server myServer -appName MyApp". If the application is remote, it is
copied to the current working directory before the installation command is
started.

cbscript.json example
[
{
"name": "Install application",
"version": "1.0.0",
"description": "This script package installs the specified application",
"command": "/bin/sh ${WAS_PROFILE_ROOT}/bin/wsadmin.sh",
"log": "${WAS_PROFILE_ROOT}/logs/wsadmin.traceout",
"location": "/opt/tmp/installapp",
"timeout": "0",
"ostype": "linux/unix",
"commandargs": "-lang jython -f /opt/tmp/installapp/install_app.jy
$APP_LOCATION $INSTALL_ARGS",
"keys":
[
{
"scriptkey": "APP_LOCATION",
"scriptvalue": "",
"scriptdefaultvalue": ""
},
{
"scriptkey": "INSTALL_ARGS",
"scriptvalue": "",
"scriptdefaultvalue": ""
}
]
}
]

Example script
Note: This example script is designed for version 7.0.0.x patterns only.
import urllib
from
from
from
from

404

java.io import File

java.lang import Boolean
java.lang import String
java.net import URL

IBM Cloud Orchestrator 2.4.0.2: User's Guide

def download(url):
fileLocs = String(url).split(/)
lastPart = fileLocs[len(fileLocs) - 1]
file = File(lastPart)
file.createNewFile()
newFileLoc = file.getAbsolutePath()
urllib.urlretrieve(url, newFileLoc)
return newFileLoc
def copyZip(binURL):
binURL = str(binURL)
url = None;
fileRemote = Boolean.FALSE
appFileLoc =
try:
url = URL(binURL)
fileRemote = Boolean.TRUE
except:
pass
if fileRemote:
print Start retrieval of + binURL
appFileLoc = download(str(binURL))
else:
print File already local + binURL
appFileLoc = File(binURL).getAbsolutePath()
return appFileLoc
binURL = sys.argv[0]
installArgs = [-usedefaultbindings]
if len(sys.argv) == 2:
installArgs = [ + sys.argv[1] + ]
appLocation = copyZip(binURL)
AdminApp.install(appLocation, installArgs)
AdminConfig.save()

Example script to configure the trace levels

This script package sets a trace specification level (example
"com.ibm.ws.ibm.*=info") on all servers in a cell. It can be included on either a
stand-alone pattern part or a Deployment Manager pattern part. Users can specify
the trace specification during deployment.

Script variables
The following parameter is included in this script package.
TRACE_SPEC:
Specifies the trace specification for the cell. This parameter is required.

cbscript.json example
[
{
"name": "Configure Trace Specification",
"version": "1.0.0",
"description": "This script package configures trace specification
on all servers in a cell",
"command": "${WAS_PROFILE_ROOT}/bin/wsadmin.sh",
"log": "${WAS_PROFILE_ROOT}/logs/wsadmin.traceout",
"location": "/opt/tmp/configtrace",
"timeout": "0",
Chapter 7. Managing and deploying virtual patterns

405

"ostype": "linux/unix",
"commandargs": "-lang jython -f /opt/tmp/configtrace/configure_trace.jy
$TRACE_SPEC",
"keys":
[
{
"scriptkey": "TRACE_SPEC",
"scriptvalue": "",
"scriptdefaultvalue": ""
}
]
}
]

Example script
Note: This example script is designed for version 7.0.0.x patterns only.
from java.lang import String
traceSpec = sys.argv[0]
nodes = AdminNodeManagement.listNodes()
for node in nodes:
nodeStr = String(node)
nodeStr = String(nodeStr.substring(0, nodeStr.indexOf(())).trim()
appServers = AdminServerManagement.listServers(APPLICATION_SERVER, nodeStr)
for appServer in appServers:
appServerStr = String(appServer)
appServerStr = String(appServerStr.substring(0, appServerStr.indexOf(())).trim()
AdminTask.setTraceSpecification([-serverName + appServerStr + -nodeName
+ nodeStr + -traceSpecification + traceSpec + -persist true])
AdminConfig.save()

Example script package to create a server

This script creates an application server on all of the custom nodes in an IBM
Cloud Orchestrator pattern or on the node part for which it is included. The script
package is intended to be used on either a Deployment Manager or stand-alone
server part in a pattern. The name of the application server is specified by the user.

Script variables
The following parameter is include in this script package.
SERVER_NAME:
Specifies the name of the server to be created on each node. If multiple
nodes exist in the pattern, the server name is augmented with a counter
that begins at 1. This parameter is required.

cbscript.json example
[
{
"name": "Server creation",
"version": "1.0.0",
"description": "This script package creates a server on each node
within the cell",
"command": "${WAS_PROFILE_ROOT}/bin/wsadmin.sh",
"log": "${WAS_PROFILE_ROOT}/logs/wsadmin.traceout",
"location": "/opt/tmp/createserver",
"timeout": "0",
"ostype": "linux/unix",
"commandargs": "-lang jython -f /opt/tmp/createserver/create_server.jy
$SERVER_NAME",
"keys":
[

406

IBM Cloud Orchestrator 2.4.0.2: User's Guide

{
"scriptkey": "SERVER_NAME",
"scriptvalue": "",
"scriptdefaultvalue": ""
}
]
}
]

Example script
Note: This example script is designed for version 7.0.0.x patterns only.
serverName = sys.argv[0]
managedNodeStr = AdminTask.listManagedNodes()
if len(managedNodeStr) != 0:
managedNodes = managedNodeStr.split("\n")
i=1
for managedNode in managedNodes:
thisServer = serverName + "_" + str(i)
AdminServerManagement.createApplicationServer(managedNode, thisServer, default)
i=i+1
else:
node = AdminControl.getNode()
AdminServerManagement.createApplicationServer(node, serverName, default)
AdminConfig.save()

Example script package to create a WebSphere Application

Server cluster
This script package can be included on a Deployment Manager part. It creates an
application server on each custom node in a cell and creates an application server
cluster from those servers. Both the cluster and server names can be specified
during deployment.

Script variables
There are two parameters included in this script package.
CLUSTER_NAME:
Specifies the name of the new cluster. This parameter is required.
SERVER_NAME:
Specifies the name of the servers. The script package automatically
appends numbers to the supplied server name to ensure that each server
name is unique. This parameter is required.

cbscript.json example
[
{
"name": "Cluster creation",
"version": "1.0.0",
"description": "This script package creates a server on each node
within the cell and then creates a cluster from those servers",
"command": "${WAS_PROFILE_ROOT}/bin/wsadmin.sh",
"log": "${WAS_PROFILE_ROOT}/logs/wsadmin.traceout",
"location": "/opt/tmp/createcluster",
"timeout": "0",
"ostype": "linux/unix",
"commandargs": "-lang jython -f /opt/tmp/createcluster/createCluster.jy
Chapter 7. Managing and deploying virtual patterns

407

$CLUSTER_NAME $SERVER_NAME",
"keys":
[
{
"scriptkey": "CLUSTER_NAME",
"scriptvalue": "",
"scriptdefaultvalue": ""
},
{
"scriptkey": "SERVER_NAME",
"scriptvalue": "",
"scriptdefaultvalue": ""
}
]
}
]

Example script
Note: This example script is designed for version 7.0.0.x patterns only.
cellName = AdminControl.getCell()
clusterName = sys.argv[0]
serverName = sys.argv[1]
managedNodeStr = AdminTask.listManagedNodes()
managedNodes = managedNodeStr.split("\n")
i=0
for managedNode in managedNodes:
appServers = AdminServerManagement.listServers(APPLICATION_SERVER, managedNode)
webServers = AdminServerManagement.listServers(WEB_SERVER, managedNode)
appSrvLen = len(appServers)
webSrvLen = len(webServers)
if appSrvLen == 0 and webSrvLen == 0:
if i == 0:
AdminTask.createCluster([-clusterConfig [-clusterName + clusterName +
-preferLocal true]])
cluster = AdminConfig.getid(/ServerCluster: + clusterName + /)
memberName = serverName + str(i)
node = AdminConfig.getid(/Node: + managedNode + /)
AdminConfig.createClusterMember(cluster, node, [[memberName, memberName ]])
i = i + 1
AdminConfig.save()

Managing add-ons
You can configure user and NIC parts in your catalog and then use them as parts
in your patterns.

Before you begin

A basic set of add-ons are provided by IBM and must be downloaded before these
steps are performed. For more information, see Add-ons in the catalog on page
409.

408

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Add-ons in the catalog

Use the console to manage virtual system pattern add-ons in the catalog. You can
use the default add-ons provided with the system, or you can clone and modify
them, or create and configure your own. You can then add them as parts to one or
more virtual system patterns.
Add-ons are specialized scripts that customize your virtual machine configuration.
Add-ons provide fine tuning for hardware and operating system configurations. A
set of basic add-ons with an initial configuration is provided. You can use these
default add-ons, clone and modify them as needed, or create new ones.
Add-ons are implemented at the following levels:
v Deployment logic provisions new hardware for disks and network interface
controllers (NICs) that cannot be customized.
v Deployment logic configures the provisioned resources. Resources are packaged
as default implementation scripts that are fully customizable. For example, the
Default add user add-on has a defaultadduser.zip package that contains a
script to define a user account.
To view the list of add-ons that are available in the catalog, click PATTERNS >
Pattern Design > Add-Ons.
After creating an add-on, it can be dropped onto a topology pattern part from the
Virtual System Patterns window. When the pattern is deployed, you provide the
customization parameters for the add-ons to customize the hardware and
operating system configuration.
The following set of default add-ons are provided with the product:
Default add NIC
Adds a new virtual network interface controller (NIC) to the virtual
machine, configures its IP address information, and activates it. Use this
add-on for virtual image parts that support communication using ssh to
run scripts after initial activation of the virtual machine.
Note: This add-on is not supported on PowerVM virtual images.
Default configure NIC
Triggers configuration via VSAE of the additional NICs present in the
image.
Note: This add-on is not supported on PowerVM virtual images.
Default add disk
Adds a virtual disk to the virtual machine and optionally formats and
mounts the disk. Prerequisite: the parted (parted RPM) and sfdisk
(util-linux RPM) tools must be installed for a Red Hat image (or other type
of packages depending on different operating systems). The prerequisite
for VMware virtual images is that the virtual disk type must be SCSI.
Default AIX add disk
Adds a virtual disk to the virtual machine and optionally formats and
mounts the disk. Use this add-on for PowerVM virtual images.
Note: IBM Cloud Orchestrator does not support the disk add-on function
for PowerVM with Shared Storage pool.

Chapter 7. Managing and deploying virtual patterns

409

Default Windows add disk

Adds a virtual disk to the virtual machine and formats and makes the disk
available under new letter. Prerequisites: PowerShell and Diskpart tools,
which are available in the default Windows installation. New disk is
partitioned using MBR schema. The prerequisite for VMware virtual
images is that the virtual disk type must be SCSI.
Default raw disk
Adds a virtual disk to the virtual machine, the disk is added raw without
partitions or formatting. For PowerVM virtual images, you must run the
cfgmgr to refresh the system configuration and to see the new disk. The
prerequisite for VMware virtual images is that the virtual disk type must
be SCSI.
Note: IBM Cloud Orchestrator does not support the disk add-on function
for PowerVM with Shared Storage pool.
Default add user
Defines an additional user on the virtual machine. The default add-on
script runs a simple add user command. No additional account
configuration is performed.

Managing add-ons with the user interface

You can manage add-ons in the catalog with the user interface and then add them
to deployable patterns.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps.

About this task

You can use, add, modify or delete the following types of add-ons in your catalog:
v Disk
v NIC
v User

Procedure
1. Navigate to the Add-Ons window by clicking PATTERNS > Pattern Design >
Add-Ons from the menu bar.
2. You can perform the following tasks:
v Adding add-ons to the catalog on page 411
v Cloning an add-on on page 412
v Editing an add-on on page 413
v Making add-ons read-only on page 414
v Associating an add-on with a pattern on page 414
v Deleting an add-on on page 415
For more information about the fields on the Add-Ons window, see Fields on
the Add-Ons user interface on page 416.

410

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Results
After completing these steps you have managed the add-ons that you can add to
parts on deployable patterns.

What to do next
After you have configured your add-ons you can work with them as parts on a
pattern in the Pattern Editor window. For more information about editing parts,
see For more information, see Configuring parts on page 447. For more
information about working with patterns, see Working with virtual system
patterns (classic) in the user interface on page 436. If you are working with a NIC
add-on, it can be configured with an environment profile. See Managing
environment profiles on page 354 for more information.

Adding add-ons to the catalog

You can add new add-ons in addition to the add-ons already included in the
product.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps. A basic set of add-ons are provided by IBM and must be downloaded before
these steps are performed.

About this task

You can either clone an existing add-on or you can create a new add-on. To clone
an existing add-on, either a default add-on or one that has been added by a user,
see Cloning an add-on on page 412. To add a new add-on to the catalog, use the
following steps.

Procedure
1. From the left panel of the Add-Ons window, click Create New to add an
Add-On to the catalog.
2. Select the add-on archive and click Import. The new add-on displays in the left
panel of the Add-Ons window. The right panel displays configuration options
for the add-on.
3. Select the type of add-on. Add-ons can be one of the following types:

4.
5.
6.
7.

Disk

Adds a virtual disk to the virtual machine and, optionally, formats and
mounts the disk.

NIC

Adds a virtual network interface controller (NIC) to the virtual

machine. NIC add-ons are deployed with environment profiles.

User Defines an additional user on the virtual machine.

Optional: Add a description to help identify the add-on.
Optional: In the Add-on package files section, provide the customized add-on
package file with the Browse field and the Upload button.
Optional: Use the Environment section to add environment variables.
Optional: Specify the standard script package parameters for the following
directories:
v Working
v Logging
Chapter 7. Managing and deploying virtual patterns

411

v Executable
v Arguments
8. Optional: Set a timeout value in the Timeout field.
9. Optional: Add or change the user permissions for this add-on with the Access
granted to field.

Results
You added a new add-on to the catalog.

What to do next
The add-on is ready to be used as a part in your patterns.

Cloning an add-on
You can create an add-on based on an existing add-on. Default add-ons are
included that can either be added as they are or cloned and edited. The cloned
add-on can then be modified to your specifications.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps.

About this task

When you clone an add-on, the copy is pre-populated with the configuration data
from the original add-on. Use this task to copy an existing add-on that can then be
edited.

Procedure
1. Locate the add-on to clone. If it is not displayed, you can search for the
add-on. From the left panel of the Add-Ons window, enter all or part of the
name of the add-on in the search field.
2. Select the add-on to clone. Click the add-on to copy from the listing on the
left panel of the Add-Ons window. Details about the add-on are displayed in
the right panel of the Add-Ons window.
3. Click the clone icon to copy the add-on you have selected.
4. Enter the name for the new add-on and click OK. The details panel for the
new add-on is now displayed and can be modified. When you have
completed the configuration for the add-on, the add-on is saved for you as
you navigate away from the Add-Ons window.
5. Optional: Add or change the description to help identify the add-on.
6. Optional: In the Add-on package files section, provide the add-on package
files in one of the following ways:
v Provide a custom add-on package using the browse function to locate your
custom package.
v Download and modify the default add-on implementation.
7. Optional: Use the Environment section to remove existing environment
variables or create new ones.
8. Optional: Configure standard script package parameters for the following
directories:
v Working

412

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Logging
v Executable
v Arguments
9. Optional: Set a time out value in the Timeout field.
10. Optional: Add or change the user permissions for this add-on.

Results
After you have completed these steps, any users or groups with access, can use the
add-on with pattern nodes.

What to do next
You can now associate this add-on with a pattern. See Working with virtual
system patterns (classic) on page 434 for more information about patterns.

Editing an add-on
You can edit any add-on that is not read-only. You can modify a add-on to suit the
changing needs of your environment.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps.

About this task

You can edit any add-ons that are not read only and to which you have write
access. This task provides information about editing existing add-ons.

Procedure
1. Select the add-on. Select the add-on you want to edit from the left panel of the
Add-Ons window. Add-ons that have the locked symbol by them cannot be
edited. Add-ons with the edit symbol beside them can be edited. The
information about that add-on is shown in the right panel of the Add-Ons
window.
2. Click the edit icon. From the top of the right panel of the Add-Ons window,
click the edit icon.
3. Edit the fields on the right panel of the Add-Ons window. For more
information about these fields, see Fields on the Add-Ons user interface on
page 416.

Results
When you have finished editing an add-on, it is ready to be added to part on a
pattern.

What to do next
You can lock the add-on against future editing. For more information, see Making
add-ons read-only on page 414. You can add the add-on to a part on a pattern.
For more information, see Working with virtual system patterns (classic) on page
434.

Chapter 7. Managing and deploying virtual patterns

413

Making add-ons read-only

Either draft or read-only add-ons can be deployed for testing or production, but
making an add-on read-only prevents further edits. Making add-ons read-only
provides consistent reuse in the cloud.

Before you begin

You must be assigned the catalogeditor role or the admin role to perform these
steps.

About this task

You can make an add-on read-only to prevent further editing to the add-on.

Procedure
1. Select the add-on. From the left panel of the Add-Ons window, select the
add-on. Add-ons that have the read-only symbol by them are already read-only
and cannot be edited. Add-ons with the edit symbol beside them are not
read-only and can be edited. Basic information about the selected add-on is
shown in the right panel of the Add-Ons window.
2. Made the add-on read-only to lock it to future editing. Click the Lock icon in
the upper right toolbar of the Add-Ons window.
3. Verify that you want to make the add-on read-only. When prompted to verify
that you want to make the add-on read only, click OK to lock the add-on.

Results
When you have made the add-on read-only, it can be cloned or deleted but it
cannot be edited.

What to do next
You can include the add-on on a part in a pattern to be deployed to the cloud. For
more information, see Working with virtual system patterns (classic) on page
434.

Associating an add-on with a pattern

You can associate an add-on with a pattern and defined cell through the user
interface.

Before you begin

The add-on must be configured. For more information about configuring the
add-on, see Editing an add-on on page 413.

About this task

Use this task to associate an add-on with a pattern.

Procedure
1. Navigate to the Virtual System Patterns window by clicking PATTERNS >
Instances > Virtual System Patterns, for virtual systems, or by clicking
PATTERNS > Instances > Virtual System Patterns (Classic), for virtual
systems (classic).

414

IBM Cloud Orchestrator 2.4.0.2: User's Guide

2. Select a pattern. In the left panel of the Virtual System Patterns window, select
the pattern with which to associate the add-on. The pattern must not be
read-only. Basic information about the selected pattern displays in the right
panel of the Virtual System Patterns view.
3. Edit the pattern. Click Edit on the upper right of the Virtual System Patterns
(Classic) window, for virtual systems (classic), or click Open on the upper right
of the Virtual System Patterns window, for virtual systems.
4. Add Add-Ons.
For virtual systems (classic): from the drop-down box in the left panel of the
Pattern Editor, click Add-Ons. A list of the add-on parts is provided that can be
dropped into the virtual image parts on the right panel of the Pattern Editor
view. This list can contain any add-ons provided for use with IBM Cloud
Orchestrator. Add-ons can then be added to the virtual image parts. You can
drop any add-on from this list onto the virtual image parts on the canvas on
the right. This associates the add-on with that part.
For virtual systems: in Pattern Builder click the image object. Then click Add a
Component Add-On and select from the list the add-on that you want to add
to the image object. This operation associates the add-on with the image part.
5. Optional: Configure any properties defined in the add-on. Properties added to
add-ons can be defined when associating the add-on with a part or it can be
defined during deployment.
For virtual systems (classic): click the edit properties icon to set the value now.
It is possible to use a variable syntax to set the value for properties where the
value is not yet known. For more information about setting the value of a
property to be variable, see Properties variable syntax on page 390.
For virtual systems: click the associated add-on object in the image part and
edit the properties of the add-on on the menu in the right side of Pattern
Builder.

Results
You added one or more add-ons to the virtual images on the pattern.

What to do next
When you have associated the add-on with a pattern, you can complete
configuration of the pattern and deploy it to the cloud group.

Deleting an add-on
You can manually delete an add-on, disassociating it with the pattern and cell,
using the user interface.

Before you begin

You must be assigned the catalogeditor role and be granted all access to the
add-on you want to remove. You can also perform these steps if you are assigned
the admin role. Add-ons that are read-only, or that are in use, cannot be deleted.
Before you delete an add-on, ensure that it is no longer needed by the pattern and
the cell with which it is associated.

About this task

This task provides information about manually deleting an add-on from the
Add-On window of the IBM Cloud Orchestrator user interface.
Chapter 7. Managing and deploying virtual patterns

415

Procedure
1. Locate the add-on. If it is not displayed, you can search for the add-on you
want to delete. From the left panel of the Add-Ons window, enter all or part of
the name of the add-on in the search field.
2. Select the add-on to delete from the listing on the left panel of the Add-Ons
window. Details about the add-on are displayed in the right panel of the
Add-Ons window.
3. Determine if it can be deleted. An add-on can only be deleted if it is not:
v Marked as read-only. The read-only icon is shown in the listing of add-ons if
it is read-only.
v Included in any patterns. If it is included in any patterns, the delete icon is
not available and the Included in patterns field displays the linked patterns
in which this add-on is included.
If the add-on is referenced by any patterns, you can click the pattern name link
in the Included in patterns field to go to the Virtual System Patterns panel for
that pattern. From this panel, you can remove the add-on part from the part, or
parts, on the pattern.
4. Delete the add-on. Click the delete icon on the top right of the Add-Ons
window.
5. Confirm the deletion. You are prompted to confirm that you want to delete the
selected add-on. Click OK to delete the add-on.

Results
The add-on is deleted from IBM Cloud Orchestrator.

Fields on the Add-Ons user interface

You can manage the add-ons in your catalog using the fields on the Add-Ons
window of the IBM Cloud Orchestrator user interface.
To work with add-ons with the IBM Cloud Orchestrator user interface you can use
the Add-Ons window.

The left panel

The left panel of the Add-Ons window provides the following options to work
with add-ons:
Create New
Click Create New to open a window in which you can define your new
add-on.
Search
Enter the name of an add-on in this field to search for it. You can use the
up and down arrow keys to sort through the listing of add-ons.
List of add-ons
The listing of add-ons contains the default add-ons that are already defined
to IBM Cloud Orchestrator, by name.
To work with an add-on, first select it from the list in the left panel of the Add-Ons
window.

416

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Icons on the upper right

The upper right of the Add-Ons window provides the following icons:
Refresh
Refreshes the status of the add-ons and updates the fields on the Add-Ons
window.
Clone Creates a copy of the add-on, even a locked add-on, that can be edited.
Lock

Makes the add-on read-only and locks it against further editing.

Delete Removes the add-on from the IBM Cloud Orchestrator catalog.

The right panel

Selecting an add-on shows the name of the add-on at the top of the right panel
and the following fields on the right panel:
Description
The description of the add-on. You can edit this description to provide
meaningful information about the add-on.
Type

The add-on can be one of the following types:

v Disk
v NIC
v User
The type of add-on is selected when the add-on is created and this field
cannot be changed after creation of the add-on.

Created on
The creation time of the add-on, as the number of seconds since midnight
January 1, 1970 UTC. When the add-on is displayed, this value is shown as
the date and time in the local timezone.
Current status
The status of the add-on can be one of the following status types:
The edit icon
The add-on can be edited.
Read-only
The add-on is locked to editing. For information about making an
add-on read-only, see Making add-ons read-only on page 414.
Updated on
Thd time the add-on was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the add-on is displayed, this value
is shown as the date and time in the local timezone. This field is read-only.
Add-on package files
If you are cloning one of the provided default add-ons, you can create
custom add-ons by downloading and modifying the add-on package. The
add-on package is defined for each type of add-on:
Default add NIC
Download the defaultaddnic.zip package.
Default configure NIC
Download the defaultconfigurenic.zip package.

Chapter 7. Managing and deploying virtual patterns

417

Default add disk

Download the defaultadddisk.zip package.
Default AIX add disk
Download the defaultaixadddisk.zip package.
Default Windows add disk
Download the defaultwinadddisk.zip package.
Default raw disk
Download the defaultaddrawdisk.zip package.
Default add user
Download the defaultadduser.zip package.
The Download link beside existing script package zip files enables these
packages in the catalog to be loaded.
For new add-ons, you can upload a custom script package by clicking the
Browse field. The Browse filed opens a system file upload window to
browse to the location of the package to load. After locating the package,
clicking the Upload button loads the add-on package to your catalog.
Environment
The environment property holds the add-on keys and default values for the
add-on. What this field contains depends on the type of add-on and the
situation in which you are viewing it:
v If you are creating a new add-on, you can define the environment
variables. The Add variable field, with the name and value entry fields,
is used to list the environment variables to add. The Add link adds the
provided environment variable to the add-on.
v If you are viewing an add-on that is read-only which has environment
variables set, those environment variables are shown.
v If you are working with a NIC add-on, there are no environment
variables that can be set. A NIC add-on must be deployed using an
environment profile.
Working directory
The directory, on the virtual machine, into which files for this add-on
package are to be placed.
Logging directory
The directory, on the virtual machine, that is to contain the log files
generated by this add-on.
Executable
Specifies the command to be invoked for this add-on package. The
executable can be a command already on the virtual machine (for example
wsadmin, tar, ant, or another system command). You can also provide your
own script to be run as part of the script package.
Arguments
The field to enter any arguments that are to be passed to the command,
the command line that is passed to the executable command. This field can
optionally contain environment variables and other valid command-line
syntax. You can also access environment using standard techniques (for
example shell, or ant.)
Timeout
The maximum amount of time to wait for this add-on to finish running on

418

IBM Cloud Orchestrator 2.4.0.2: User's Guide

a virtual machine. Specify the timeout as the number of milliseconds to

wait, or 0 to wait indefinitely for the add-on to complete.
Access granted to
The access control list for this add-on. Users or projects who have access
this add-on are listed in this field as links. The Add more... entry field
enables the owner or anyone with proper access to the add-on to provide
access for more projects.

Working with virtual system patterns

Use the Self-service user interface to manage virtual system patterns in IBM Cloud
Orchestrator.
You can manage virtual system patterns in the Virtual System Patterns and Pattern
Builder pages in the Self-service user interface. Virtual system patterns implement
deployment topologies that are created using one or more virtual images and
applications in the system catalog.
You can use the virtual system patterns provided by IBM Cloud Orchestrator
without modification and deploy them to the cloud. You can also create new
patterns, or make a copy (clone) of an existing pattern, and use the Pattern Builder
to modify the pattern to alter the topology and configuration of your
environments.

Creating virtual system patterns

Use the Self-service user interface to create virtual system patterns.

Before you begin

You must be granted access to patterns, or access to create patterns, to complete
this task.

About this task

Use the Pattern Builder to create virtual system patterns. When you start the
Pattern Builder, it opens in a separate window. If you are using Microsoft Internet
Explorer Version 7 or Version 8, you might need to change your browser settings
so that the Pattern Builder is displayed correctly. Specifically, configure pop-up
windows to open in a new tab in the current window. From the browser menu,
click Tools > Internet Options.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns.
2. Click Create New.
3. Build your virtual system pattern:
a. Select a virtual system template or start from a blank pattern.
b. Set the Name and Version for the virtual system pattern.
Note: Use a unique name and version combination for the pattern. If you
attempt to create a pattern with the same name and version as an existing
pattern, an error is displayed.
c. Click Start Building.

Chapter 7. Managing and deploying virtual patterns

419

The Pattern Builder opens in a new web browser page where you can
build the virtual system pattern.
4. Specify the properties for the pattern in the pattern properties pane:
Name The name of the virtual system pattern.
Version
The version of the virtual system pattern.
Description
The description of the virtual system pattern. This field is optional.
Type

Leave Pattern selected to create a virtual system pattern or select

Pattern Template to create a virtual system template that is used as
the basis for creating other virtual system patterns.

Lock option for plugin usage

Specify how this virtual system pattern is affected by upgrades to the
pattern type or to IBM Foundation Pattern.
Unlock plugins
If the pattern type is upgraded, use the latest versions of
pattern type plug-ins. If IBM Foundation Pattern is upgraded,
use the latest version.
Lock all plugins
Do not change the version of plug-ins or the version of the
IBM Foundation Pattern that is associated with this virtual
system pattern when an upgrade occurs.
Lock all plugins except Foundation plugins
If the pattern type is upgraded, do not change the version of
the plug-ins that are associated with this virtual system
pattern. If IBM Foundation Pattern is upgraded, use the latest
version.
Note: If you select Lock all plugins or Lock all plugins except
Foundation plugins, you can view a list of which plug-ins are locked.
Click the Source tab in Pattern Builder. The application model source
is displayed. Search for the element plugins to view the list.
5. If you selected a blank template, the canvas is empty and you can start
building the virtual system pattern. If you selected a template, customize the
virtual system pattern:
a. Drag the assets that you want to add to the virtual system pattern onto the
canvas.
Note:
v When you add an asset to the canvas, the properties for that asset are
displayed in the right pane. The properties vary depending on the asset
that you add. Required properties are denoted by a red asterisk. If a
required property is not set, a warning icon displays on the asset in the
canvas.
v The right pane displays the properties for the asset that is selected on
the canvas. You can access the settings for an asset by selecting it on the
canvas.

420

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Some properties have a lock symbol next to their value in the right
pane. If you lock a property by clicking this symbol, that property is not
configurable from the deployment page when a user deploys the virtual
system pattern.
v Some properties have an icon with a green arrow next to them. Click
this icon to add a reference to a component-level or pattern-level
parameter as the value for the attribute, and create an explicit data
dependency link. After you click the icon, the Add a reference page is
displayed:
Select whether you want to reference a component-level parameter or
a pattern-level parameter.
Then, select the component and an output attribute for that
component that you want to reference.
Click Add to create the reference.
Tip:
For example, if your pattern contains a DB2 component and a
WebSphere Application Server component, you might want the
db_user parameter for the DB2 component to reference the WASROOT
output attribute of the WebSphere Application Server component.
Refer to the documentation for the pattern that you are using for
specific details about its components and attributes.
v If you want to remove an asset from the canvas, click Remove
component on the asset.
v After you build your pattern, you can change to the List View tab to
view the topology as a vertical list of components. You can configure the
values for the properties in the pattern from the canvas, or from the List
View tab.
Images
Virtual images provide the operating system and product binary
files that are required to create a virtual system instance. Some
virtual images include only the operating system files, while others
also include product binary files.
If multiple versions of the image are available, such as 8.5.5.0
and 8.5.5.1, select the version that you want to deploy with the
pattern after you add the image to the canvas.
Scripts
Scripts can include almost any set of executable files and artifacts
that are valid for the target virtual machine environment. Create
these scripts on your local workstation, in IBM PureApplication
System, or by using the Plug-in Development Kit. Then, import the
script package to the system so that it is available in the catalog
and in the Assets palette in the Pattern Builder.
Note:
v Scripts cannot be added to the canvas directly. You must add
them to images or components.
v If multiple versions of the script are available, such as 1.0 and
2.0, select the version that you want to use with the pattern
after you add the script to the canvas.

Chapter 7. Managing and deploying virtual patterns

421

v You cannot add scripts to some images, such as the DataPower

image. If an image does not support scripts, a message displays
on the canvas when you attempt to add the script to the image.
Software Components
Software components install, and possibly configure software on
the virtual system pattern. You can drag a software component
onto a virtual image that is on the canvas. If you drag a software
component directly onto the canvas, it is automatically added to a
virtual image that meets the requirements for that software
component.
If multiple versions of the software component are available, select
the version that you want to deploy with the pattern after you add
the software component to the canvas.
b. Edit the connections between assets, as needed. To add a link between two
assets, hover over one of the assets until the blue circle turns orange.
Helper text describes the asset that is associated with the link. Select the
circle, drag a connection to the second asset until the asset is highlighted,
and then release. When you create a link between two assets, you can map
a property of one asset to a property of the asset to which it is linked.
For example, you might have one image with a software component that
requires a DB2 server, and another image with a software component that
installs a DB2 server. You can link the software component to the DB2
server. When you create the link, you are prompted to map the properties
between the two assets. You can map the DB2 server IP address property
for the first software component to the Server IP address property for the
second software component.
c. Add policies to the pattern or a component, as needed.
You can apply a policy globally at the pattern level, or apply it to a
specific component that supports the policy. When you apply a policy
globally, it is applied to all components in the virtual system pattern that
support it. If you apply a policy to a specific component and also apply it
to the whole virtual system pattern, the configuration of the
component-specific policy overrides the pattern level policy.
To add policies to the virtual system pattern, click Add policy to pattern
and select a policy, or select a component part on the canvas and click the
Add a Component Policy icon to add a component-specific policy. You can
add these policies to the pattern or a component:
iFix policy
Add an interim fixes policy to install emergency fixes during
deployment to the pattern or to a particular virtual machine,
depending on whether you apply the policy at the pattern-level or
component-level. After you add the interim fix policy, choose one
or more fixes from the list to apply at deployment time. The fixes
that display in the list are emergency fixes that were uploaded to
the emergency fixes catalog (through Catalog > Emergency Fixes)
or to the Installation Manager repository (through Catalog > IBM
Installation Manager Repository).
Interim fixes in the Emergency Fixes catalog can be configured to
be applicable to an image, plug-in, or middleware. Only fixes that
are applicable to an image, plug-in, or middleware that is in the
pattern are displayed.

422

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Interim fixes in the IBM Installation Manager repository can be

configured to be applicable to middleware. Only fixes that are
applicable to middleware that is in the pattern are displayed.
Security policy
Add a security policy to configure whether Secure Shell (SSH)
password login is available. If you configure this policy at the
component-level, SSH log-in is disabled for the virtual machine
that deploys for the image where the policy is set. If you configure
this policy at the pattern-level, SSH log-in is configured for all
virtual machines that deploy as part of the pattern.
Base Scaling Policy
Scaling is a runtime capability to automatically scale your virtual
system instance as the load changes. A scaling policy component
defines this capability and the conditions for processor and
memory, under which scaling activities are performed.
Specify the following attributes for the scaling policy:
Number of instances
Specifies the number of cluster members that are hosting
the instance. The default value is 1. The acceptable value
range is 2 - 10. This attribute is required.
Instance number range of scaling in and out
Specifies the scaling range for instance members that are
hosting the topology. The default range for this attribute is
1 - 10. The acceptable value range is 1 - 50. This attribute is
required.
Maximum vCPU count per virtual machine
Specifies the maximum number of virtual processors that
are used by the topology.
The acceptable value range is 2 - 16.
Maximum memory size per virtual machine
Specifies the maximum amount of virtual memory, in
gigabytes, that are used by your application.
CPU Based
Scaling in and out when CPU usage is out of threshold
range Specifies the processor threshold condition to start
scaling activity. When the average processor use of
a virtual machine is out of this threshold range, the
specified scaling action is taken. If the policy is set
at the pattern level, scaling actions are taken if the
processor use of any virtual machine in the
topology is out of the threshold range. If the policy
is set at the component level, scaling actions are
taken if the processor use of the virtual machine
where the component is running is out of the
threshold range. The acceptable value range is 0 100%.
Minimum time (seconds) to trigger add or remove
Specifies the time duration condition to start

Chapter 7. Managing and deploying virtual patterns

423

scaling activity. The default value is 300 seconds.

The acceptable value range is 30 - 1800. This
attribute is required.
scaling by
Specifies the action to take when scaling is
triggered. You can select add vCPU only, add or
remove nodes, or add or remove nodes; add
vCPU first and then add nodes.
Memory Based
Scaling in and out when memory usage is out of
threshold range
Specifies the memory threshold condition to start
scaling activity. When the average memory usage
of your topology is out of this threshold range, the
specified scaling action is taken. The default value
is 20 - 80%. The acceptable value range is 0 100%.
Minimum time (seconds) to trigger add or remove
Specifies the time duration condition to start
scaling activity. The default value is 300 seconds.
The acceptable value range is 30 - 1800. This
attribute is required.
then scaling by
Specifies the action to take when scaling is
triggered. You can select add virtual memory only,
add or remove nodes, or add or remove nodes;
add virtual memory first and then add nodes.
Note: If the middleware requires a restart before
its virtual memory can be increased, such as with
IBM WebSphere Application Server, the
middleware is restarted in a rolling method so that
there is no downtime during the scaling.
Note: You can select CPU-based scaling, memory-based scaling, or
both. If you select more than one type, the relationship between
the types is handled by the system as an OR. For example, if you
select processor and memory-based scaling, with the action to add
or remove a node, this action is triggered if the condition set for
either processor or memory scaling is met.
Routing policy
Add a routing policy to configure the topology or component for
Elastic Load Balancing (ELB). After you add the policy, specify the
following attributes for the routing policy:
Endpoint
The endpoint is the URL that is used to access the
application through Elastic Load Balancing.
Port

424

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Enter the port that is used by the topology (for a

pattern-level policy) or component (for a component-level
policy). This port is opened on the firewall when the
pattern deploys.

Enable HTTPS
Specify whether HTTPS is used by the topology (for a
pattern-level policy) or component (for a component-level
policy). If you select Enable HTTPS, you must enter the
port that the topology or component uses for HTTPS. If the
port is specified, it is opened on the firewall when the
pattern deploys.
6. Optional: Click the Add a Component Add-on icon on the image to add an
add-on. For more information about add-ons, see the Related concepts
section.
7. Optional: Click Advanced Options on the canvas to configure advanced
options. The advanced options that are available depend on the topology of
the virtual system pattern you are editing.
Note: When you open the advanced options editor for a new virtual system
pattern that has no advanced options set, the displayed settings are the
recommended values for the topology.
8. Optional: If your pattern includes a WebSphere Application Server software
component, configure these properties:
v Specify the location of the WebSphere Application Server installation.
Note: This property is mapped to the installation directory property of the
WebSphere Application Server software component, so it should be
populated automatically. If it is not populated, enter the installation location
manually.
v If there is more than one WebSphere Application Server on the node, and
you want to specify the order in which the servers are restarted, specify the
order in the WAS Servers Restarting Order property. Enter the server
names in the required order. Separate the server names with semicolons.
v Specify the WebSphere Application Server user name.
9. Set the order of deployment for each of the components in the pattern.
a. Use the Move up and Move down options on software components and
scripts to determine the order in which components are started.
b. Change to the Ordering tab to change the order for other components in
the pattern. You can also modify the order for software components and
scripts from this tab.
10. Click Save.

What to do next
When creating virtual system patterns, you can use the Pattern Builder to specify
an OS prerequisite list or a set of global package installation options that are
required by a component in the metadata of the system plug-in. The Red Hat
Update Infrastructure (RHUI) Service or the Red Hat Satellite Service must be
deployed in the cloud group before you deploy the pattern, which allows virtual
machine clients to download and install the RPMs using these services. The RHUI
Service provides a Yellowdog Updater, Modified (YUM) repository.
If you are a software component developer and need to ensure certain Red Hat OS
RPMs are installed in the image, you must ensure that they are described in the
metadata.json file. For example, to add MySQL and VNC packages to the
deployed virtual machines automatically, you can add a stanza to the
metadata.json file as shown in the following text:
Chapter 7. Managing and deploying virtual patterns

425

"configurations": {
-"partsKey": "Yum",
-"packages": [
-"YUM"],
-"prereq_os_packages": [
-{
-"packages": [
-"mysql",
-"vnc"],
-"type": "yum"}]},

During pattern deployment, OS packages can be added or removed from the list
specified by the Pattern Builder, and can override deployment policies at a virtual
machine level or a pattern level for the entire pattern with multiple virtual
machines.

Importing virtual system patterns

You can import virtual system patterns so that you can edit and deploy the
imported topology for use in your system.

Before you begin

You must have access to patterns, or access to create patterns, to complete this
task.

About this task

You can import virtual system patterns that were previously exported. The version
for the pattern is retained when you import the pattern. You can use the
Self-service user interface or the command-line interface to complete this task. If
you use the Self-service user interface to import a pattern, you can import only the
pattern model. To import pattern artifacts (script packages, add-ons, images, or
software packages) along with the pattern, use the command-line interface instead.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns.
2. Click the Import icon on the toolbar.
3. Click Browse to select the compressed file that contains the pattern that you
want to import.
4. Click Import.
v If there are no existing patterns on the system with the same name and
version as the pattern that you are importing, the pattern is imported.
v If a pattern with the same name and version exists on the system, and one or
both of the patterns are not read-only, you are prompted with options:
a. Specify a unique name for the imported pattern.
Note: This option is available only when the pattern that you are
importing is not read-only.
b. Specify a unique version for the imported pattern.
Note: This option is available only when the pattern that you are
importing is not read-only.
c. Replace the existing pattern.

426

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: This option is available only when the existing pattern is not
read-only.
After you make a selection, click Import again to complete the import
process.
v If a pattern with the same name and version exists on the system, and both
of the patterns are read-only, the import fails.

What to do next
After you import your virtual system, you can edit the model and deploy it into
the system.

Cloning virtual system patterns

You can clone an existing virtual system pattern and then customize the copy for
your environment.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns.
2. Select a virtual system pattern.
3. Click the Clone icon on the toolbar.
4. Provide the following information about the new virtual system pattern:
Name Enter a unique name for the virtual system pattern in the Name field.
Virtual images
Select a different virtual image than the image that is used in pattern
for any of the virtual images that are in the pattern as needed.
5. Click OK. When the information is processed, the Virtual System Patterns page
displays. The virtual system pattern that you created is added to the list. Select
the cloned virtual system pattern to display more details about the pattern.
6. Click the Open icon to open the cloned virtual system pattern in the Pattern
Builder. Edit the virtual system pattern as needed. You can add or remove
images, and then you can add or remove software components, script packages,
add-ons, and policies. You can also add or update property mappings between
components.
7. When you are finished editing the pattern, click Save.

What to do next
You can lock the virtual system pattern against future editing. For more
information about making virtual system patterns read-only, see the related links.
You can also deploy the virtual system pattern to the cloud. For more information
about deploying, see the related links.

Exporting virtual system patterns

You can export virtual system patterns from the system catalog so that you can use
them on a different system.

Before you begin

You must have access to patterns, or access to create patterns, to complete this
task.

Chapter 7. Managing and deploying virtual patterns

427

About this task

You can export a virtual system pattern so that you can use it on a different
system. When you export a pattern, the version for the pattern is preserved. You
can use the Self-service user interface or the command-line interface to complete
this task. If you use the Self-service user interface to export a pattern, you can
export only the pattern model. To export pattern artifacts (script packages,
add-ons, images, or software packages) along with the pattern, use the
command-line interface instead. For information about using the command-line
interface, see the related links.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns.
2. Click Export on the toolbar.
3. Click Save to save the compressed file for the pattern to a local directory.

Deleting virtual system patterns

You can delete virtual system patterns that you no longer want to deploy.

Before you begin

You must have access to the topology to complete this task.

About this task

You can use the Self-service user interface, the command-line interface, or the REST
API to complete this task. For the command-line and REST API information, see
the related links.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns.
2. If the pattern has multiple versions, expand the entry for the pattern.
3. Click Delete in the Actions column for the pattern that you want to delete or
select the virtual system pattern and click Delete on the virtual system pattern
details page.
4. Click Confirm to confirm that you want to delete the pattern.

Modifying virtual system patterns

You can modify any virtual system pattern that is not read-only.

Before you begin

You must be granted access to the virtual system pattern to complete this task.

About this task

Use the Pattern Builder in the Self-service user interface to edit your virtual system
pattern. You can add, edit or remove components, links, and policies.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns.
2. Select the virtual system pattern that you want to modify.

428

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: If the pattern has multiple versions, expand the entry for the pattern,
and then select the version that you want to modify.
3. Click Open on the toolbar.
4. Modify the pattern, as needed. For more information about the assets that are
available, see the "Creating virtual system patterns" topic in the related links.
If you want to preserve the previous configuration for the pattern, you can save
the modified pattern as a different version by changing the value in the
Version field. You also have the option to set a different version when you save
the pattern.
5. Save the pattern:
v Click the Save icon to save the pattern with the same name and version. This
option overwrites the existing pattern with the specified name and version.
v Click Save as to change the name or version for the pattern. This option
preserves the original pattern, and saves the modified pattern with the new
name and version. If you change only the version, the pattern is displayed
by name, and you can expand the entry to see all versions of the pattern.

Making virtual system patterns read-only

You can deploy both draft and read-only virtual system patterns for testing or
production. Making a virtual system pattern read-only prevents further edits to the
topology definition and ensures consistent reuse in the cloud.

Before you begin

You must have edit access to the virtual system pattern that you want to make
read-only. If the pattern is read-only already, you cannot change it. To make a
virtual system pattern read-only, ensure that no one with the permission to edit the
virtual system pattern intends to change it.

About this task

You can make virtual system patterns read-only to prevent further editing of the
virtual system pattern.
Note: When you make a virtual system pattern read-only, it is possible for the
pattern to contain script packages, add-ons, or images that are still in draft state
(that is, unlocked). The pattern model is unchanged, but it is still possible to
modify the script package, add-on, or image if it is not also locked.
You can use the Self-service user interface, the command-line interface, or the REST
API to complete this task. For the command-line and REST API information, see
the related links.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns. Virtual system
patterns that have a status of Read-only cannot be edited. Virtual system
patterns that have a status of Draft can be edited.
2. Select the virtual system pattern that you want to make read-only to show the
pattern details.
3. To lock editing of the virtual system pattern, click the Lock icon in the toolbar
of the Pattern details page.
You are prompted with a list of any unlocked components in the pattern that
can be modified even if the pattern is read-only.
Chapter 7. Managing and deploying virtual patterns

429

4. Click Confirm to lock the virtual system pattern or Cancel to discard the
changes.
CAUTION:
You cannot unlock a virtual system pattern after you lock it.

Results
If you clicked Confirm to lock the virtual system pattern, the pattern is now
read-only.
Note: If the pattern contains one or more script packages or add-ons that are not
locked, the Current status field in the Virtual System Patterns details page is
displayed with the following status:
Read-only (The pattern content can still be modified because some script packages,
add-ons, or images are not read-only)

You can lock your script packages and add-ons as needed before you deploy the
virtual system pattern. To lock a script package or add-on, return to the
appropriate catalog page in the console, select the script package or add-on, and
use the Lock function to change the state to read-only.

Deploying virtual system patterns

After you create a virtual system pattern, you can provision and deploy it to the
cloud. You can deploy a virtual system pattern multiple times and each
deployment is a running virtual system instance on the cloud infrastructure.

Before you begin

Configure the virtual system pattern, and ensure that it is ready to be deployed.
For more information about modifying virtual system patterns, see the related
links.
Script packages that are included in your virtual system pattern can contain license
agreements that you must accept before you can deploy the pattern. For more
information about accepting license agreements, see the related links.
To deploy patterns to an externally managed environment profile, all of the
components in your pattern must use IBM Foundation Pattern version 2.1.0.0 or
later, whether for single-system or multisystem deployment, and must not contain
a Hypervisor Edition virtual image.

About this task

You can deploy either draft or committed virtual system patterns for testing or
production. The time that it takes to deploy a virtual system depends on several
factors, such as the size of the virtual system pattern parts and the
interdependencies of parts in the pattern definition, network usage, storage usage,
and the provisioning speed of the virtual machine on the cloud infrastructure.
Note: Connectivity issues with the DNS server can cause increased deployment
times or failed deployments. The network administrator for the target network
must check the routing tables of the DNS server to ensure that it can resolve the
network address of the system.

430

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: After upgrading to 2.4.0.x, when deploying a virtual system pattern created
in IBM Cloud Orchestrator 2.4 that uses Linux images, you are prompted for the
password of the virtuser user (the default non-root user to access the deployed
virtual machines). Provide the additional information in the virtual system pattern
deployment dialog or modify the pattern by using the Pattern Editor.

Procedure
1. Click PATTERNS > Pattern Design > Virtual System Patterns.
2. Click Deploy in the Actions column for the pattern that you want to deploy,
or select the pattern that you want to deploy and click Deploy on the toolbar.
On the Configure pane:
3. Edit the name for the deployment, if needed. This name displays on the
Instances page after the pattern deploys.
4. Select the environment profile that you want to use for the deployment.
v If the network for the selected environment profile is set to Internally
Managed:
Select a Cloud Group and an IP Group.
Note: You can also set the IP group for each virtual machine on the
Distribute pane. You cannot change the Cloud Group for the
deployment after you configure it on this pane.
The deployment is limited to a single cloud group.
If the network for the selected environment profile is set to Externally
Managed, you select the cloud group and IP group for the deployment
later, on the Distribute pane.
5. Set the priority for the deployment.
v

Note: For more information about deployment priorities, see the Related
tasks.
6. Modify the deployment schedule as needed:
v Choose Start now, or choose Start later and select a date and time for the
deployment to start.
v Choose Run indefinitely, or choose Run until and select a date and time
for the deployment to end.
7. Optional: To set up SSH access, use one of the following options in the SSH
Key section to set the public key:
v To generate a key automatically, click Generate. Click Download to save
the private key file to a secure location. The default name is id_rsa.txt.
The system does not keep a copy of the private key. If you do not
download the private key, you cannot access the virtual machine, unless
you generate a new key pair. You can also copy and paste the public key
into a text file to save the key. Then, you can reuse the same key pair for
another deployment. When you have the private key, make sure that it has
the correct permissions (chmod 0400 id_rsa.txt). By default, the SSH client
does not use a private key file that provides open permission for all users.
v To use an existing SSH public key, open the public key file in a text editor
and copy and paste it into the SSH Key field.
Important: Do not use cat, less, or more to copy and paste from a
command shell. The copy and paste operation adds spaces to the key that
prevent you from accessing the virtual machine.

Chapter 7. Managing and deploying virtual patterns

431

The SSH key provides access to the virtual machines in the cloud group for
troubleshooting and maintenance purposes. See the topic, "Configuring SSH
key-based access", for details about SSH key-based access to virtual machines.
8. Modify the pattern and component attributes as needed.
The attributes that display in the pattern configuration column are attributes
from the pattern and components in the pattern that are not locked from
editing. You can modify existing values or set values that were not specified
during pattern creation. Be sure that all required fields have values.
Components that have a blue dot next to the name contain required attributes
that must be set before the pattern is deployed.
9. When you are finished configuring all of the fields on the Configure tab, click
Continue to distribute.
On the Distribute pane:
The virtual machines in the deployment are placed in cloud groups by the system.
10. Optional: To modify the placement of the virtual machines, drag the virtual
machines to different cloud groups.
v If you drag a virtual machine cell that contains more than one virtual
machine, you are prompted to select the number of virtual machines that
you want to move. You must select the number from the list in the dialog.
After you move a virtual machine to a different cell, the IP group
assignments are set to default values. If needed, you can edit the virtual
machine network settings in the next step to modify the IP group.
v If you modify the placement of the virtual machines, the new placement is
validated to ensure that the necessary resources and artifacts are available
in the selected cloud group.
v If there is a problem with the placement, a message is displayed. Resolve
the issue with the placement before you continue.
For example, if this message displays when you modify the placement:
CWZKS7002E Insufficient memory to place the pattern, move the virtual
machine to a different cloud group with sufficient memory resources for the
pattern.
If you see the error: Unable to assign to cloud group, there is an error
with the location, cloud group, NIC or IP groups for the cell where the
error is displayed. If this error message occurs, you must resolve the issue
with that cell before you are allowed to drag a virtual machine to that cell
for placement there. Hover your mouse over the error to display more
details about the problem in a pop-up window.
11. To edit the network or storage volume settings for a virtual machine, hover
your mouse over the virtual machine icon and click the pencil icon.
a. On the IP Groups tab, you can modify IP group for each of the NICs in
the virtual machine. The IP groups that are listed are associated with the
environment profile that you chose for the deployment. If the IP address
provided by field in the environment profile that you chose for the
deployment is set to Pattern Deployer, you must set the IP address for
each NIC in the deployment.
b. If there is a Default attach block disk add-on in the pattern, you can
modify the storage volumes for the virtual machine on the Storage
Volumes tab. You can use an existing storage volume or create one to
attach to the component during deployment. If you choose to create a new
storage volume, configure these settings:
Name Set the name for the storage volume.

432

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Description
Optional. Set a description for the storage volume.
Size (GB)
Set the size for the storage volume, in GB.
Volume Groups
Select a volume group for the storage volume. A storage volume
group is a logical grouping of volumes that can span workloads
and cloud groups.
c. Click OK when you are finished updating the settings.
12. When you are finished modifying the settings, click Deploy.
When the virtual system is deployed, the virtual system instance is listed
under the Virtual System Instances section of the IBM Cloud Orchestrator
Self-service user interface. To view the virtual system instance, click
PATTERNS > Instances > Virtual System Instances.
The virtual memory and virtual processor settings that are configured for the
virtual images in the virtual system pattern must be met by the requirements
for the software components in the pattern. If these requirements are not met,
the deployment fails and an error message that lists the memory and
processor requirements is displayed. If this error occurs, modify the processor
and memory settings in the pattern so that the requirements are met, and
deploy the pattern again.
13. View the details of the virtual system instance in the Virtual System Instances
page.

Results
The placement is validated again to ensure that the resources and artifacts that
were used for validation during the initial placement are still available. If there is a
problem with the placement, an error message is displayed, and a red circle is
displayed on the circle that contains errors. Hover over the cell that contains
errors, and then hover over the yellow triangle in the resulting pop-up window to
view more details about the errors. Resolve the issue with the placement, such as
moving the virtual machine to a different system with sufficient resources so that
the deployment can continue.
After placement validation is successful, the virtual system instance is deployed
and started. To stop the virtual system instance, select the virtual system instance
from the list, and click Stop. To start the virtual system instance again, select the
virtual application click Start.
To remove a stopped topology, select it from the Virtual System Patterns page,
and click Delete.
Note: When deploying instances to a VMware region, the name specified at
deployment time is propagated from the Self-service user interface to the
OpenStack component. The instance is created in the VMware hypervisor using the
corresponding OpenStack UUID. To match an instance in OpenStack with the
actual instance deployed on VMware, complete the following steps:
1. On the Region Server where the deployment occurred, run the nova list
command and identify the instance UUID in the command output.
2. In the vCenter client, in the search field, type the instance UUID and press
Enter.

Chapter 7. Managing and deploying virtual patterns

433

What to do next
After you deploy the virtual system instance, you can use the IP address of the
virtual machines to access the application artifacts. For example, you can manually
enter the URL in your browser.
http://IP_address:9080/tradelite/

IP_address is the IP address of the deployed WebSphere Application Server virtual

machine.
If you uploaded an SSH public key during the deployment, you can also connect
directly to a virtual machine without a password if you have the private key.

Deploying Business Process Manager 8.5.5 and DB2 10.5

virtual system patterns
This scenario describes how to deploy Business Process Manager 8.5.5 and DB2
10.5 virtual system patterns.

Procedure
1. Because a base image license is not included in a Business Process Manager
pattern, you must provide the base image. For example, you can use the IBM
OS Image for Red Hat Linux Systems V2.1.0.1 (
CN3CHML), or you can create a
base image as described in Creating base images on page 332.
2. Import the DB2 pattern (CN30GML), if you want to use Business Process Manager
patterns with the embedded DB2. The DB2 pattern (CN30GML) is included in the
Business Process Manager 8.5.5 pattern license, so, when you search CRT40ML for
the Business Process Manager 8.5.5 pattern, you find also the DB2 pattern to be
downloaded. For information about importing a virtual system pattern, see
Importing virtual system patterns on page 426.
3. Import the Business Process Manager 8.5.5 virtual system pattern. For
information about importing a virtual system pattern, see Importing virtual
system patterns on page 426.
4. Clone the predefined Business Process Manager pattern and make necessary
changes, such as adding flavor settings. For information about cloning a virtual
system pattern, see Cloning virtual system patterns on page 427.
5. Deploy the pattern. For information about deploying a virtual system pattern,
see Deploying virtual system patterns on page 430.

Working with virtual system patterns (classic)

Using a virtual system pattern, you can describe the topology of a system that you
want to deploy. Virtual system patterns provide repeatable system deployment that
can be reproduced. To build virtual system patterns, you can use parts from one or
more virtual images, add-ons, and script packages.

About this task

To work with virtual system patterns (classic), perform the following steps:

Procedure
1. Use the user interface, as described in Working with virtual system patterns
(classic) in the user interface on page 436.

434

IBM Cloud Orchestrator 2.4.0.2: User's Guide

2. Configure the advanced options. You can configure advanced options for the
virtual system patterns, as described in Configuring advanced options on
page 449.

Supported virtual system patterns (classic)

You can use predefined virtual system patterns that are provided by IBM, or you
can clone them and customize the copies to create new virtual system patterns that
are more suitable to your environment.
Patterns can be downloaded from the IBM PureSystems Centre.
For example, you can download the following virtual system patterns:
v DB2 Enterprise Server Edition
v IBM WebSphere Application Server Hypervisor Edition
Note: Not all patterns might work for all Hypervisors.
The virtual system patterns have been tested successfully on the following
operating systems:
v SUSE Linux Enterprise Server 11 SP1, SP2, or SP3, 32-bit or 64-bit.
v Red Hat Enterprise Linux 5.x, Red Hat Enterprise Linux 6.1, 6.2, 6.3, 6.4, 6.5, or
6.6 32-bit or 64-bit.
v CentOS 6.3 or 6.4, 64-bit Windows 2008 R2 64-bit,
v Windows 7 64-bit, Windows Server 2012 64-bit, Windows 8 64-bit.
To start working with a virtual system pattern, choose any of the following
options:
v Use a predefined virtual system pattern.
If one of the predefined virtual system patterns meets the needs of your
environment, you can use it without altering it and deploy it to the cloud. For
details, refer to Using a predefined virtual system pattern (classic) on page
437.
v Clone an existing virtual system pattern.
If one of the predefined virtual system patterns closely meets your needs but
you must customize it, you can clone the virtual system pattern and then
modify the copy. For details, refer to Cloning an existing virtual system pattern
(classic) on page 438.
v Create a virtual system pattern.
If the predefined or cloned virtual system patterns do not meet the needs of
your environment, you can create a virtual system pattern. For details, refer to
Creating a virtual system pattern (classic) on page 440.

Chapter 7. Managing and deploying virtual patterns

435

Working with virtual system patterns (classic) in the user

interface
Virtual system patterns implement deployment topologies from one or more
virtual images and applications from the IBM Cloud Orchestrator catalog.

Before you begin

Review the available virtual system patterns, including the virtual system patterns
provided by IBM. You can then determine if an existing virtual system pattern is
suitable to your environment or if there is one that you can customize to be
suitable. See Supported virtual system patterns (classic) on page 435 for
information about the provided virtual system patterns.

About this task

You can use the virtual system patterns provided by IBM, as they are, and deploy
them to your cloud. You can also use the IBM Cloud Orchestrator virtual system
pattern editor to alter the topology and configuration of your environments. In a
single virtual system pattern, you can include parts from multiple images and you
can drag script packages and add-ons onto any of the parts in the virtual system
pattern. You can configure parameters for the parts. If the script packages or
add-ons you are using have parameters, you can also configure the parameters.
Information about each of the fields in the Virtual System Patterns (Classic)
window is provided in Virtual system pattern (classic) windows on page 469.

Procedure
1. From the menu, open the Virtual System Patterns (Classic) window by clicking
PATTERNS > Instances > Virtual System Patterns (Classic).
2. Determine the task to perform. You can perform the following tasks with the
IBM Cloud Orchestrator user interface:
Determine the virtual system pattern to use.
You can use a predefined virtual system pattern, clone an existing
virtual system pattern, or create a virtual system pattern, as described
in Selecting a virtual system pattern (classic) on page 437.
Edit a virtual system pattern.
You can edit any virtual system pattern that is not read-only and which
you have permission to edit, as described in Editing a virtual system
pattern (classic) on page 442.
Configure advanced options.
You can edit and configure the advanced options for a virtual system
pattern, as described in Configuring advanced options on page 449.
Make a virtual system pattern read-only.
If you want to lock a virtual system pattern to future editing, you can
make it read-only, as described in Making virtual system patterns
(classic) read-only on page 463.
Deploy a virtual system pattern.
You can deploy the virtual system pattern after you have configured it,
as described in Deploying a virtual system pattern (classic) on page
464.

436

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Delete a virtual system pattern.

You can delete a virtual system pattern that you do not need any more,
as described in Deleting a virtual system pattern (classic) on page
468.

Selecting a virtual system pattern (classic)

You can use a set of predefined virtual system patterns that is provided by IBM.
You can also clone an existing IBM Cloud Orchestrator virtual system pattern to
customize it or create a virtual system pattern.

Before you begin

Review the available virtual system patterns, including the virtual system patterns
provided by IBM. Determine if an existing virtual system pattern is suitable to
your environment or if there is one that you can customize to be suitable. See
Supported virtual system patterns (classic) on page 435 for information about the
provided virtual system patterns.

About this task

You can use the predefined virtual system patterns provided by IBM, as they are,
clone and edit an existing virtual system pattern, or create a virtual system pattern.

Procedure
v Use a predefined virtual system pattern. If one of the predefined virtual system
patterns meets the needs of your environment, you can use it without altering it
and deploy it to your cloud. See Using a predefined virtual system pattern
(classic) for more information.
v Clone an existing virtual system pattern. If one of the predefined virtual system
patterns closely meets your needs but you must customize it, you can clone the
virtual system pattern and then edit the copy. See Cloning an existing virtual
system pattern (classic) on page 438 for more information. See Editing a
virtual system pattern (classic) on page 442 for more information.
v Create a virtual system pattern. If the predefined or cloned virtual system
patterns do not meet the needs of your environment, you can create a virtual
system pattern. See Creating a virtual system pattern (classic) on page 440 for
more information.

What to do next
When you have completed any necessary work with the virtual system pattern,
you can deploy the virtual system pattern to your cloud. See Deploying a virtual
system pattern (classic) on page 464 for more information.
Using a predefined virtual system pattern (classic):
You can use a set of predefined virtual system patterns that is provided by IBM.
Virtual system pattern are made up of parts from one or more virtual images, and
script packages from the IBM Cloud Orchestrator catalog. Virtual system patterns
provide a topology definition for repeatable deployment that can be shared.
Before you begin
Review the virtual system patterns provided by IBM Cloud Orchestrator to
determine which virtual system pattern best fits your needs. See Supported
Chapter 7. Managing and deploying virtual patterns

437

virtual system patterns (classic) on page 435 for information about these virtual
system patterns.
About this task
You can use the virtual system patterns provided by IBM Cloud Orchestrator, as
they are, and deploy them to your cloud.
Procedure
1. From the list in the left panel select a predefined virtual system pattern.
2. Add it to the cloud. Click the Deploy icon to provide the necessary information
to deploy this virtual system pattern.
3. Deploy the virtual system pattern. When all of the information is provided
correctly in the Deploy pattern dialog, click OK to deploy the virtual system
pattern. A green check mark beside each entry indicates that the information
has been provided. For more information about deploying a virtual system
pattern, see Deploying a virtual system pattern (classic) on page 464.
Results
The virtual system pattern is now running in the virtual system instance.
Cloning an existing virtual system pattern (classic):
IBM provides a set of predefined virtual system pattern that you can clone.
Because the predefined virtual system patterns cannot be edited, cloning them
provides a starting point for creating customized virtual system patterns that work
in your environment.
Before you begin
You must be granted access to the pattern and be assigned the catalogeditor role
or the admin role.
Select a virtual system pattern that most closely meets your needs. See Supported
virtual system patterns (classic) on page 435 for virtual system pattern
descriptions.
Because virtual system patterns are associated with virtual images, if you have not
accepted the license for the virtual image with which the virtual system patterns
are associated, the Clone option is not available. If the clone function is not
available for the virtual system pattern you want to use, accept the license for the
image associated with the virtual system pattern. To accept the license, click
PATTERNS > Pattern Design > Virtual Images. See Chapter 6, Managing virtual
images, on page 331 for more information about virtual images.
Important: You can accept a license and then change the image that the virtual
system pattern is using when you define the cloned virtual system pattern. If you
change the image and do not actually use the image for which you accepted the
license, you are not charged for that license.
About this task
This task provides the necessary steps to clone a virtual system pattern and then
customize the copy to meet the needs of your environment.

438

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. From the left panel Virtual System Patterns (Classic) window, select a virtual
system pattern to clone. The description and general information about this
virtual system pattern display in the right panel of the Virtual System Patterns
(Classic) window.
2. Clone the virtual system pattern. Click the clone icon on the upper right panel
of the Virtual System Patterns (Classic) window.
3. You can provide the following basic information about the new virtual system
pattern you are cloning:
Name Enter a unique name for the virtual system pattern in the Name field.
This information is required to clone a virtual system pattern.
Description
Optionally, enter a detailed description to identify the virtual system
pattern in the Description field.
Virtual image
Select a virtual image with which to associate the virtual system pattern
from the listing. This information is required to clone a virtual system
pattern. You can edit the new virtual system pattern to associate
individual parts with different virtual images. If all the parts in the
virtual system pattern you are cloning are from a single virtual image,
use this option. This option switches all of the parts to a different
virtual image in the new virtual system pattern. If the original virtual
system pattern contains parts from different virtual images, this option
is disabled. If this option is disabled, the parts in the new virtual
system pattern are associated with the same virtual images as the
corresponding parts in the original virtual system pattern.
4. Click OK to save your changes. When the information is processed, you return
to the Virtual System Patterns (Classic) window and the virtual system pattern
you created is added to the list in the left panel. It is selected so that the
information about it is shown in the right panel. For more information about
the fields on this panel, see Virtual system pattern (classic) windows on page
469.
5. Edit the virtual system pattern. To change the virtual system pattern topology,
click the edit icon on the upper right panel of the Virtual System Patterns
(Classic) window. You can perform the following actions with virtual system
patterns:
v Add or remove parts
v Edit parts
v Add or remove script packages to the parts
v Add or remove add-ons to the parts
v Configure properties for the parts and parameters for the script packages
that have parameters
v Define advanced options
v Modify the start up order of the parts
The Pattern Editor window provides a list of parts. For more information about
the interaction of the parts on the Pattern Editor window, see Virtual system
pattern (classic) editing views and parts on page 443.
6. Edit the parts on the canvas. See Editing a virtual system pattern (classic) on
page 442 for more information about editing functions you can perform on
virtual system patterns.
Chapter 7. Managing and deploying virtual patterns

439

7. Edit advanced options. Default advanced options are provided with the virtual
system patterns but you can edit those settings. For more information, see
Configuring advanced options on page 449.
8. Complete the virtual system pattern. When you have finished editing this
virtual system pattern, click the Done editing link on the upper right panel of
the Pattern Editor window. This virtual system pattern is listed on the left
panel of the Virtual System Patterns (Classic) window.
Results
When you have completed these steps, you have cloned the virtual system pattern
and it can be customized.
What to do next
You can lock the virtual system pattern against future editing. For more
information, see Making virtual system patterns (classic) read-only on page 463.
You can deploy the virtual system pattern to the cloud. For more information, see
Deploying a virtual system pattern (classic) on page 464.
Creating a virtual system pattern (classic):
You can create a virtual system pattern using the IBM Cloud Orchestrator user
interface. Virtual system patterns are topology definitions for repeatable
deployment that can be shared.
Before you begin
You must be assigned the catalogeditor role or the admin role.
Review the predefined virtual system patterns to ensure that none of the existing
virtual system patterns can be cloned and customized to meet your needs. For
more information about the predefined virtual system patterns, see Supported
virtual system patterns (classic) on page 435.
About this task
You can create a virtual system pattern by cloning an existing virtual system
pattern or by creating a virtual system pattern. This task provides the steps for
creating a virtual system pattern.
Procedure
1. Add a virtual system pattern. On the upper left panel of the Virtual System
Patterns (Classic) window, click Add to provide the following basic information
about the virtual system pattern you are creating.
Name Enter a unique name for the virtual system pattern in the Name field.
This information is required to create a virtual system pattern.
Description
Optionally, enter a detailed description to identify the virtual system
pattern in the Description field.
2. Click OK to indicate that you have finished editing and return to the initial
view of the virtual system pattern. When the information is processed, you
return to the Virtual System Patterns (Classic) window and the virtual system
pattern you created is added to the list in the left panel. It is selected so that

440

IBM Cloud Orchestrator 2.4.0.2: User's Guide

the information about it is shown in the right panel. For more information
about the fields on this panel, see Virtual system pattern (classic) windows
on page 469.
3. Edit the virtual system pattern. To change the virtual system pattern topology,
click edit on the upper right panel of the Virtual System Patterns (Classic)
window. You can perform the following actions:
v Add or remove parts
v Edit parts
v Add script packages to the parts
v Add or remove add-ons to the parts
v
v
v
v
v

4.

5.

6.
7.

Remove script packages from the parts

Configure properties for the parts
Configure parameters for script packages that have them
Define advanced options
Modify the start up order of the parts

The Pattern Editor window provides a list of parts. For more information about
the interaction of the parts on the Pattern Editor window, see Virtual system
pattern (classic) editing views and parts on page 443.
Edit the parts on the canvas. See Editing a virtual system pattern (classic) on
page 442 for more information about editing functions you can perform on
virtual system patterns.
Edit advanced options. Default advanced options are provided with the virtual
system patterns but you can edit those settings. For more information, see
Configuring advanced options on page 449.
Optional: Modify the default order in which the parts run at deployment. See
Ordering parts to run at deployment on page 446 for more information.
Indicate that you have finished editing and return to the initial view of the
virtual system pattern. When you have finished editing this virtual system
pattern, click the Done editing link on the top of the right panel of the Pattern
Editor window.

Results
When you have completed these steps, you have configured basic information
about the virtual system pattern you have created and it can be deployed to the
cloud.
What to do next
You can lock the virtual system pattern against future editing. For more
information, see Making virtual system patterns (classic) read-only on page 463.
You can deploy the virtual system pattern to the cloud. For more information, see
Deploying a virtual system pattern (classic) on page 464.

Chapter 7. Managing and deploying virtual patterns

441

Editing a virtual system pattern (classic)

You can edit any virtual system pattern that is not read-only. You can modify a
virtual system pattern to suit the changing needs of your environment.

Before you begin

You can edit virtual system patterns that are not read-only and locked to editing. If
a virtual system pattern can be edited, the edit icon is shown beside it. If a virtual
system pattern is locked to editing, the locked icon is shown beside it.
To modify an existing virtual system pattern that is not read-only, you must have
either created the virtual system pattern or have been given the correct user access.
The owner for each virtual system pattern is shown on the Virtual System Patterns
(Classic) window for that virtual system pattern. If you do not have write access to
the virtual system pattern you want to edit, you can request access from that
owner.

About this task

You can edit any virtual system patterns that are not read only and to which you
have write access. This task provides information about editing existing virtual
system patterns.

Procedure
1. Select the virtual system pattern you want to edit from the left panel of the
Virtual System Patterns (Classic) window. Details about the virtual system
pattern are shown in the right panel of the Virtual System Patterns (Classic)
window.
2. From the top of the right panel of the Virtual System Patterns (Classic) window,
click the edit icon The Virtual System Patterns (Classic) window opens for this
virtual system pattern.
3. Edit the parts on the canvas.
a. Select a part from the lists on the left panel of the Pattern Editor window.
The lists of parts, script packages, and add-ons show available parts that
can be dropped onto the editing canvas on the right side of the Pattern
Editor window.
b. Drop the selected parts onto the editing canvas on the right of the Pattern
Editor window.
The editing canvas graphically shows the topology of the virtual system
pattern. See Virtual system pattern (classic) editing views and parts on page
443 for information about the virtual image parts and the interaction between
them.
4. Optional: Configure advanced options. For more information, see Configuring
advanced options on page 449.
5. Optional: Configure the order in which the parts are to deploy. For more
information, see Ordering parts to run at deployment on page 446.
6. Indicate that you have finished editing and return to the initial view of the
virtual system pattern. When you have finished editing this virtual system
pattern, click the Done editing link on the top of the right panel of the Virtual
System Patterns (Classic) window.

442

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Results
When you have finished editing this virtual system pattern, it is ready to be
deployed to the cloud.

What to do next
You can lock the virtual system pattern against future editing. For more
information, see Making virtual system patterns (classic) read-only on page 463.
You can deploy the virtual system pattern to the cloud. For more information, see
Deploying a virtual system pattern (classic) on page 464.
Virtual system pattern (classic) editing views and parts:
A virtual system pattern, that is not read-only, can be edited if you have
permission to edit it. The topology for a virtual system pattern is graphically
shown. Virtual image parts, add-ons, and script packages can be dropped onto an
editing canvas to create or change relationships between the parts that define the
topology.
The Virtual System Patterns (Classic) window
When you select a virtual system pattern to edit in Virtual System Patterns
(Classic) window, you can see information about the virtual system pattern. The
topology of the virtual system pattern is shown on the right panel of the Virtual
System Patterns (Classic) window. For more information about the predefined
virtual system patterns and what they provide, see Supported virtual system
patterns (classic) on page 435.
The Pattern Editor window
Clicking the edit icon on the upper right panel of the Virtual System Patterns
(Classic) window opens the Pattern Editor window for the selected virtual system
pattern. The Pattern Editor window provides lists to select virtual image parts,
add-ons, and script packages.
Virtual image parts
Selecting the Parts list on the Pattern Editor provides a listing of the parts that can
be dropped onto the virtual system pattern canvas. The virtual system pattern
canvas is on the right panel of the Virtual System Patterns (Classic) window. The
following virtual image parts are examples of the parts available for IBM
WebSphere Application Server Hypervisor Edition images:
v Administrative agents
v
v
v
v
v
v

Custom nodes
Deployment manager
IBM HTTP servers
Job manager
Stand-alone server
On-demand router: The on-demand router part is available if you are using the
WebSphere Application Server 7.0.0.17 with Intelligent Management Pack image.

These parts are determined by the virtual images you are using. For more
information about virtual images, see Chapter 6, Managing virtual images, on
page 331.
Chapter 7. Managing and deploying virtual patterns

443

Some virtual image parts represent multiple instances. These graphical parts on the
editing canvas have a badge that shows the number of instances of the part. A
valid number of instances that can be specified is 1 - 999.
You can configure the parts either when you deploy the virtual system pattern or
directly from the part before deployment. To configure the part before deploying it,
click the edit properties icon for the part on the editing canvas. For more
information about configuring the parts, see Configuring parts on page 447.
Script packages
The Scripts list on the Pattern Editor provides a listing of the script package parts
that can be dropped into the virtual image parts. Virtual image parts are on the
right panel of the Virtual System Patterns (Classic) window. This list can contain
script packages associated with the virtual image and any that you have defined
for use with IBM Cloud Orchestrator. For more information about script packages,
see Adding a script package on page 367 and Associating a script package with
a pattern on page 371. Script packages can then be added to the virtual image
parts.
Add-ons
The following default add-ons are provided with IBM Cloud Orchestrator and can
be added to parts on the editing canvas:
Default add NIC
Adds a new virtual network interface controller (NIC) to the virtual
machine, configures its IP address information, and activates it. Use this
add-on for virtual image parts that support communication using ssh to
run scripts after initial activation of the virtual machine.
Note: This add-on is not supported on PowerVM virtual images.
Default configure NIC
Triggers configuration via VSAE of the additional NICs present in the
image.
Note: This add-on is not supported on PowerVM virtual images.
Default add disk
Adds a virtual disk to the virtual machine and optionally formats and
mounts the disk. Prerequisite: the parted (parted RPM) and sfdisk
(util-linux RPM) tools must be installed for a Red Hat image (or other type
of packages depending on different operating systems). The prerequisite
for VMware virtual images is that the virtual disk type must be SCSI.
Default AIX add disk
Adds a virtual disk to the virtual machine and optionally formats and
mounts the disk. Use this add-on for PowerVM virtual images.
Note: IBM Cloud Orchestrator does not support the disk add-on function
for PowerVM with Shared Storage pool.
Default Windows add disk
Adds a virtual disk to the virtual machine and formats and makes the disk
available under new letter. Prerequisites: PowerShell and Diskpart tools,
which are available in the default Windows installation. New disk is

444

IBM Cloud Orchestrator 2.4.0.2: User's Guide

partitioned using MBR schema. The prerequisite for VMware virtual

images is that the virtual disk type must be SCSI.
Default raw disk
Adds a virtual disk to the virtual machine, the disk is added raw without
partitions or formatting. For PowerVM virtual images, you must run the
cfgmgr to refresh the system configuration and to see the new disk. The
prerequisite for VMware virtual images is that the virtual disk type must
be SCSI.
Note: IBM Cloud Orchestrator does not support the disk add-on function
for PowerVM with Shared Storage pool.
Default add user
Defines an additional user on the virtual machine. The default add-on
script runs a simple add user command. No additional account
configuration is performed.
Customized versions of each of these add-on types can also be available if a user
has cloned or created new add-ons in the catalog. For more information about
managing add-ons in the catalog, see Managing add-ons on page 408. Add-ons
are run before script packages.
Parts on the editing canvas
When you drop the parts onto the canvas on the right panel of the Virtual System
Patterns (Classic) window, they interact in specific and predictable ways. Though
there are no columns visible and there are no column labels on the canvas, objects
fall into general groups. The objects are placed in the following general locations
on the canvas:
Managers on the left
The left side of the editing canvas contains parts that act as managers
managing other parts. For example, this column contains deployment
mangers and job managers. These managers manage the objects (nodes and
connections) in the other two sections. You can add a manager and then
add the nodes and the nodes federate to the manager. Or, you can add the
nodes and then add a single manager and the nodes federate to the
manager. You can have both a deployment manager and a job manager in
one virtual system pattern.
Nodes in the center
The center area contains managed nodes, for example custom nodes,
administrative agents or stand-alone nodes. The nodes are automatically
federated into the managers in the left column. Administrative agents are
registered with the job manager. Stand-alone servers can be federated to a
deployment manager if one is present.
Connections on the right
The right area contains connection parts. For example, the right of the
editing canvas can contain IBM HTTP Server parts that route the traffic for
the nodes. The right area can also contain an On demand routers part if
you are editing a virtual system pattern from an IBM WebSphere
Application Server Hypervisor Edition Intelligent Management Pack
virtual image.

Chapter 7. Managing and deploying virtual patterns

445

Interaction between virtual image parts

Virtual image parts can be defined to interact with other virtual image parts. When
the interacting virtual image parts are included in the same virtual system pattern,
cross configuration results. For example, when a custom node (or IBM HTTP
Server) and a deployment manager are placed in the same virtual system pattern,
they are automatically cross configured. This results in the custom node being
federated to the deployment manager. Similarly, administrative agents (or
deployment managers) are registered with a job manager.
Virtual image parts can be cross configured if the virtual system pattern editor can
determine a unique relationship. If it is unable to do so, no cross configuration
occurs. For example, if a custom node is added to a virtual system pattern with
two deployment managers, no federation takes place. However, if one of the
deployment managers is later removed, cross configuration occurs because a
unique relationship now exists.
If you have enabled the WebSphere Application Server 7.0.0.17 with Intelligent
Management Pack or later image, an on-demand router part is available to use in
your virtual system patterns. If the on-demand router part is used in a custom
virtual system pattern, a deployment manager part that is enabled with Intelligent
Management Pack is also required. Without the deployment manager part that is
enabled for the Intelligent Management Pack, virtual system patterns with
on-demand router part are not valid. However, if there is a deployment manager
part that is enabled with Intelligent Management Pack, a custom node part that is
enabled with Intelligent Management Pack is not required.
You can use the version indicator on the parts to ensure that they are referencing
the same version of the virtual image in the catalog. For example, the deployment
manager part and the on-demand router part must reference a virtual image
version that is enabled with Intelligent Management Pack. These two parts
reference the same version of the virtual image in the catalog. If the version of a
part is incorrect, you can change it when the part is on the editing canvas.
Hovering over the part name opens a window with additional information about
the virtual image.
Ordering parts to run at deployment:
When you create a virtual system pattern, parts, scripts and add-ons run in a
specific order at deployment. Add-ons always run before scripts, for example. You
can change the order in which parts and scripts run with the user interface.
Before you begin
To modify the order of the parts that are deployed for an existing virtual system
pattern (that is not read-only), you must have either created the virtual system
pattern or have been given the correct user access. The owner for each virtual
system pattern is shown on the Virtual System Patterns (Classic) window for that
virtual system pattern. If you do not have write access to the virtual system
pattern you want to edit, you can request access from that owner.
Note: The order of default parts cannot be edited when they are grayed out. The
ordering on these parts is the default ordering provided by a virtual system
pattern template.

446

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

You can change the order in which parts, and some scripts, run when a virtual
system pattern is deployed. You can order any scripts that run when the virtual
machine is created. You cannot order any scripts that are initiated by a user and
you cannot order deletion script packages.
Procedure
1. Select the virtual system pattern you want to edit from the left panel of the
Virtual System Patterns (Classic) window.
2. From the upper right of the Virtual System Patterns (Classic) window, click the
edit icon. The Pattern Editor window is opened for the selected virtual system
pattern.
3. Click Ordering from the upper right of the Pattern Editor window. The right
editing panel of the Pattern Editor window displays the parts by category: part
or script.
4. Change the order of the parts. You can order the parts to deploy by group.
Groups of parts are numbered and labelled with the clock icon. Dragging the
parts adds constraints. Parts can be moved between groups or to create new
groups. Parts within a group do not necessarily deploy in the order in which
they are shown within the group. The groups do deploy relative to the other
groups above and below them. The text to the left of the part and script listing
describes the order of deployment for each part.
5. Indicate that you have finished editing and click Topology to return to the
initial view of the virtual system pattern. When you have finished editing this
virtual system pattern, click the Done editing link on the top of the right panel
of the Pattern Editor window.
Results
When you have finished editing this virtual system pattern, it is ready to be
deployed to the cloud.
What to do next
You can configure the advanced options, or deploy the virtual system pattern to
the cloud. For more information, see Configuring advanced options on page 449
and Deploying a virtual system pattern (classic) on page 464.

Configuring parts
Before deploying a virtual system pattern to run in a cloud group, you must first
configure the parts included in the virtual system pattern.

Before you begin

You can configure the parts included in your virtual system pattern in the
following ways:
v You can configure the part when you deploy the virtual system pattern.
v You can configure the part properties from the editing canvas of the Pattern
Editor window.
For more information about modifying the pattern or configuring advanced
options, see the related links.

Chapter 7. Managing and deploying virtual patterns

447

About this task

To configure parts for a virtual system pattern, the particular virtual system
pattern is either open and being edited or it is being deployed. When editing part
properties from the virtual system pattern, you can lock the values so that they
cannot be changed during deployment. The parts that require information are
different depending on the type of virtual image to be deployed and the type of
hypervisors in the cloud. For example, parts for an WebSphere Application Server
image would require different configuration than parts for a DB2 image.

Procedure
1. Open the Properties configuration panel for the part by using one of the
following methods:
Editing the virtual system pattern
From the Virtual System Patterns (Classic) window, select the virtual
system pattern to edit and click the Edit icon. For each virtual image
part requiring information, click the Properties icon on the part. You
can also configure any script packages or disk or user add-ons on the
parts. NIC add-ons require an environment profile for configuration.
Deploying the virtual system pattern
To deploy a virtual system pattern from the Virtual System Patterns
(Classic) window, click the Deploy icon. on the upper right of the
Virtual System Patterns (Classic) window. When deploying a virtual
system pattern, you must describe the virtual system instance that you
want to deploy. As part of that process, the parts in the virtual system
pattern to deploy are listed.
When the information for each of the virtual image parts in your
virtual system pattern is provided, a green check mark is shown to the
left of the virtual image part. If information for one of these parts is
missing, then the check box to the left of the Configure virtual parts
field does not contain a green check mark. In this case, click Configure
virtual parts and then click the link for the virtual image part that is
missing information.
2. Provide the necessary information. Part properties vary, depending on the type
of part you are editing, and the scripts and add-ons it includes. If the script
packages have parameters, you can also edit these properties.
You can edit the following properties for add-ons while editing the part or
during the deployment process:
Disk add-on
Has the following properties to edit:
v DISK_SIZE_GB
v FILESYSTEM_TYPE
v MOUNT_POINT
Raw disk add-on
Has the following properties to edit:
v DISK_SIZE_GB
v FILESYSTEM_TYPE
Note: The FILESYSTEM_TYPE property is read-only.
User add-on
Has the following properties to edit:

448

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v USERNAME
v PASSWORD
v Verify password
Note: NIC add-ons require an environment profile for configuration.
3. Optional: Lock the properties. If you are editing part properties from the virtual
system pattern, you can lock the values so that they cannot be changed during
deployment. Use the unlocked or a locked icons next to each field on the
Properties window to change the status of the field. By default, the parts
properties are not locked so you must lock them if you want to prevent them
being changed during deployment.

Results
The virtual image parts for the virtual system pattern are configured.

What to do next
Deploy the virtual system pattern to the cloud.

Configuring advanced options

When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.

Before you begin

Ensure that you have access to edit the virtual system pattern you want to work
with and that it is not read-only. You can configure advanced options for virtual
system patterns you have created or virtual system patterns you have access to
edit.

About this task

When you have created or edited the initial topology for a virtual system pattern,
there are additional advanced options that you can configure. Advanced options
include messaging, session persistence, and global security. The options that are
available depend on the topology of the virtual system pattern you are editing. The
predefined virtual system patterns provided by IBM are of two basic types of
topologies: single server virtual system patterns and cluster virtual system
patterns.
Important: It may happen that advanced options are not available at all. It
depends on the items that were used in the topology of the virtual system pattern
you created.

Procedure
1. From the left panel of the Virtual System Patterns (Classic) window, select the
virtual system pattern.
2. Put the virtual system pattern in edit mode. Click the Edit icon at the top of the
right panel to see the topology of the virtual system pattern and edit it.
3. Edit the advanced options. Click the Advanced Options... link on the right
panel of the Pattern Editor window. The options available on this panel depend
on the topology of the virtual system pattern you are editing.

Chapter 7. Managing and deploying virtual patterns

449

Important: When you open the advanced options editor for a new virtual
system pattern that has no advanced options set, default settings are shown for
the virtual system pattern. These settings are recommended values for the
topology. To accept these default values for this topology, click OK. To return to
the virtual system pattern without setting these default values, click Cancel.
The following general options are available:
Single server virtual system patterns
v Enable session persistence
v Global security
For detailed information about advanced configuration options for
single server virtual system patterns, see Configuring advanced
options for single server virtual system patterns (classic) on page 461.
Cluster virtual system patterns
v Define clusters
Enable messaging
Enable session persistence
Global security
For more information about the advanced configuration options for
cluster virtual system patterns, see Configuring advanced options for
cluster virtual system patterns (classic) on page 451.
IBM WebSphere Application Server Hypervisor Edition Intelligent
Management Pack cluster virtual system patterns
If the cluster virtual system pattern you are editing is from an
Intelligent Management Pack image, then the following options are also
available:
v Define dynamic clusters
v Enable overload protection
v Configure standard health policies
v On demand router-dependent health policies
For more information about the advanced configuration options for
Intelligent Management Pack cluster virtual system patterns, see
Configuring advanced options for Intelligent Management Pack on
page 455.
4. Save your changes. When you change the settings and click OK, your changes
are saved in place of the default values.
5. Optional: Configure advanced messaging options for cluster virtual system
patterns. If you are working with a cluster virtual system pattern and you want
to configure advanced messaging for it, see Configuring advanced messaging
for databases on page 460.
6. Optional: Enable the database implemented session persistence option. If you
are enabling session persistence for either a cluster or single server virtual
system pattern, you must enable the database implemented session persistence.
See Configuring database implemented session persistence for Derby on page
463 for more information.

What to do next
You can perform the following tasks after configuring the advanced options for a
virtual system pattern:

450

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Configure the parts

For more information about configuring the parts in your virtual system
pattern, see Configuring parts on page 447.
Make the virtual system pattern read only
For more information about locking the virtual system pattern against
future editing, see Making virtual system patterns (classic) read-only on
page 463.
Deploy the virtual system pattern
For more information about deploying the virtual system pattern to a
cloud, see Deploying a virtual system pattern (classic) on page 464.
Configuring advanced options for cluster virtual system patterns (classic):
You can use the advanced virtual system patternconfiguration function as a
starting point in configuring the cluster virtual system pattern that defines your
cell.
Before you begin
Configure the parts and topology for your cluster virtual system pattern before
configuring the advanced options. When you open the advanced options editor for
a new cluster virtual system pattern, default settings are shown for the virtual
system pattern. These settings are typical default values for the topology. To accept
these default values for this topology, click OK. To return to the virtual system
pattern without setting these default values, click Cancel.
About this task
The following options are available when you are editing a cluster virtual system
pattern:
v Define clusters
Enable messaging
Enable session persistence
Global security
Procedure
1. Define clusters. Use this option to configure the number of clusters and
application servers on the deployment manager part. You can configure
messaging, session persistence, and global security. Using the define clusters
option provides the following features, all of which you can change:
v An application cluster with the default name prefix HVWebCluster
v A default number of clusters
v A default number of servers per node
The server names are in the prefix + cluster index + node name + server
index format, as shown in the following example:
HVWebCluster_1_myNode_1

2. Enable messaging. Use this function to configure additional message engine

configuration on the deployment manager part. Messaging engines point to
WebSphere Derby on the deployment manager. On the virtual system instance,
start Derby or configure the deployment manager to use another database.

Chapter 7. Managing and deploying virtual patterns

451

Important: You must have the Define clusters option selected to work with
messaging.
For more information about advanced configuration for WebSphere Application
Server clustered messaging engines or a sample authentication alias for
databases, see Configuring advanced messaging for databases on page 460.
Use the following options to configure messaging with IBM Cloud
Orchestrator:
Standard messaging engine configuration
When configuring the standard Java Message Service (JMS), IBM Cloud
Orchestrator provides the following function:
v An application cluster with the default name prefix HVMsgCluster
(which you can change)
v A default number of clusters (which you can change)
v A default number of servers per node (which you can change)
v A Service Integration Bus (SIBus), the name of which has the
HVSIBUS prefix, is created for each message cluster
v A messaging engine (ME) is defined on each member of the cluster,
because each message cluster is added to the SIBus
v A Derby Java Database Connectivity (JDBC) provider and Derby data
source are defined for use by the messaging engine or engines
defined. See Configuring advanced messaging for databases on
page 460 for more information.
v An example authentication alias provides configuration options for
the messaging engine to a database other than Derby
v Activation in only one of the members as the messaging cluster
members are started
Highly available messaging engine configuration
Processed over standard Java Message Service (JMS) support, this
option provides messaging engine failover. For a high availability
messaging WebSphere Application Server configuration, there is one
messaging engine running at a time for each SIBus. The messaging
engine can run in multiple application servers, specifically the other
members of the messaging cluster. If the server in which it is currently
running becomes unavailable, it is activated in another of the servers of
the messaging cluster with which the messaging engine is associated.
All messages are preserved because the messaging engine state is saved
in Derby. Messaging engines are activated in different application
servers. The advanced configuration scripts create both the appropriate
schemas and the high availability group OneOfNPolicy core group
policies for messaging engine election and activation.
Note: Multiple messaging engines can run in a given application
server.
Scalable messaging engine configuration
Processed over standard Java Message Service (JMS) support, this
option enables multiple messaging engines to run in a WebSphere
Application Server SIBus at a time. Therefore, the message flows for the
various JMS applications can be divided or partitioned across the
different messaging engines. Scalable messaging provides a greater
number of messages that are processed by the WebSphere Application
Server JMS support and therefore a scalable implementation.

452

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The advanced configuration scripts create multiple messaging engines

for the SIBus, specifically one for each member of each HVMsgCluster.
The default is one cluster and two members. Then, multiple messaging
engines are activated when HVMsgCluster members are started. The
OneOfNPolicy core group policies are created for each messaging
engine ensuring the messaging engine to cluster member mapping.
The appropriate schemas and high availability group policies for
messaging engine election and activation are also created.
Note: Multiple messaging engines can run in a given application
server.
Highly available and scalable messaging engine configuration
Provides multiple messaging engines to run in multiple cluster
members for each SIBus. The provided scripts handle the schema
definitions, core group policies, and message engine to member
mappings. With this configuration, messaging traffic can be divided
across multiple messaging engines. If an application server goes down,
any messaging engines are activated in the remaining cluster members.
Note: Multiple messaging engines can run in a given application
server.
Enable MQ messaging
In addition to these messaging options, the Enable MQ messaging
option provides some of the traditional WebSphere MQ configuration
options available with WebSphere Application Server. It provides
additional MQ link configuration on the deployment manager part.
Note: Newer features in WebSphere Application Server that use
WebSphere MQ as an external Java message service (JMS) provider are
available. These features are based on how you create your JMS
application resources. However, if your messaging application does not
support this approach, IBM Cloud Orchestrator provides features based
on server configuration. For details, see the information about
configuring JMS resources for WebSphere MQ messaging provider in
the WebSphere Application Server information center.
The following options provide configuration for two servers:
MQ link configuration
Select the WebSphere MQ link configuration option to perform
the following function:
v Create new transport chains for the WebSphere MQ link and
associate them with each messaging engine. These transport
chains are basic if no security exists or SSL if security is
enabled.
v Create the WebSphere MQ link
v Create the foreign bus and associate it with the WebSphere
MQ link
When defining the WebSphere MQ link there are items that use
WebSphere MQ configuration attributes. You must adjust these
attributes, for example the sample host, port, and user IDs, to
reflect your actual WebSphere MQ environment.

Chapter 7. Managing and deploying virtual patterns

453

MQ server configuration
Select the WebSphere MQ server configuration option to
perform the following function:
v Create new transport chains for the WebSphere MQ server
and associate them with each messaging engine. These
transport chains are basic if no security exists or SSL if
security is enabled.
v Create the WebSphere MQ server
v Add the WebSphere MQ server to the SIBuses
When defining the WebSphere MQ server there are items that
use WebSphere MQ configuration attributes. You must adjust
these attributes, for example the sample host, port, virtual
queue manager name, and user IDs, to reflect your actual
WebSphere MQ environment.
3. Enable session persistence. HVWebCluster or application clusters are created
with associated replication domains. Therefore, you can use the hyper text
transfer protocol (HTTP) session replication. If the replication domain is
defined, no resources are created or used unless session replication is
configured. You can use the Enable session persistence option and then one of
the following options to use HTTP session persistence:
Memory-memory implemented session persistence
The HTTP session memory bit is set on all the HVWebCluster servers.
Database implemented session persistence
On the virtual system instance, the JDBC data source created must be
updated on the deployment manager with valid host, port, user name,
and password values. The appropriate client drivers for your database,
for example jars and libraries, must be installed on your WebSphere
systems.
To use this option on the virtual system instance, the JDBC data source
created must be updated on the deployment manager. JDBC data
source must have valid host, port, user name, and password values.
The appropriate client drivers for your database, for example jars and
libraries, must be installed on your WebSphere Application Server
systems. IBM Cloud Orchestrator performs the following operations:
v Creates a DB2 JDBC provider
v Creates a sample DB2 data source, with dummy values for the host,
port, ID, and password
v Sets up a session manager on each HVWebCluster server to do HTTP
session to the database, using the sample data source and dummy
connection values
For important information about suppling a database that an HTTP
session over the database supports, see Configuring database
implemented session persistence for Derby on page 463.
4. Enable global security. Use the global security option to perform the following
function:
v Set the global security admin bit
v Use the WIM user registry that is provided with IBM Cloud Orchestrator
v Use both LTPA and BasicAuth for authentication (BasicAuth is needed for
stand-alone clients)
v Use an SSL-allowed policy for CSIv2

454

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Turn off single sign-on interoperability

v Configure secure file transfer between the deployment manager and the node
agents
v Use the high availability manager for the secure DCS channel
Using global security provides the option to use secure messaging. Use secure
messaging to perform the following function:
v Set the security bit on the SIBus
v Reduce the set of users that can connect to the SIBus. Only the WebSphere
Application Server ID created with the CB UI can connect. The default value
for that ID is virtuser.
v Disable the InboundBasicMessaging transport for the messaging engines
v Adds the virtuser ID to the sender role for foreign buses for MQLink
configurations
Results
You have configured the advanced options for the virtual system pattern.
What to do next
If you are editing parts for WebSphere advanced cluster or WebSphere advanced
cluster (development) virtual system patterns from an WebSphere Application
Server 7.0.0.17 with Intelligent Management Pack image, then there are more
advanced options you can configure. For more information, see Configuring
advanced options for Intelligent Management Pack.
Depending on the database you are using, you can configure advanced messaging.
For more information, see Configuring advanced messaging for databases on
page 460.
Configuring advanced options for Intelligent Management Pack:
If you are working with virtual system patterns from an IBM WebSphere
Application Server Hypervisor Edition Intelligent Management Pack image, there
are additional advanced options that you can configure.
Before you begin
When you open the advanced options editor for an Intelligent Management Pack
virtual system pattern, default settings are shown for the virtual system pattern.
These settings are recommended values for the topology. To accept these default
values for this topology, click OK. To return to the virtual system pattern without
setting these default values, click Cancel.
For information about basic advanced options configuration, see Configuring
advanced options on page 449.
About this task
In addition to the basic advanced options described in Configuring advanced
options on page 449, you can also configure advanced options specifically for
Intelligent Management Pack virtual system patterns. Advanced options enable
you to use a policy-based approach to managing your applications. You can
enforce application health actions with no service disruption.
Chapter 7. Managing and deploying virtual patterns

455

Procedure
1. Define dynamic clusters. Select this option to begin to define dynamic clusters
across the custom node parts in the virtual system pattern.
a. Create dynamic clusters. Select this option to create dynamic clusters across
all custom node parts in the virtual system pattern. You can set values for
the following parameters:
v
v
v
v
v
v

DYNAMIC_CLUSTER_PREFIX
NUMBER_OF_DYNAMIC_CLUSTERS
MAXIMUM_INSTANCES_PER_NODE
MAXIMUM_NODES
MINIMUM_TOTAL_INSTANCES
MAXIMUM_TOTAL_INSTANCES

v SERVER_INACTIVITY_TIME: Specify the time unit in minutes.

b. Create ODR dynamic clusters. Select this option to create on demand
router (ODR) dynamic clusters across all ODR nodes in the virtual system
pattern.
c. Enable elasticity mode. Select this option to enable the elasticity mode of
the application placement controller. You can set values for the following
parameters:
v ELASTICITY_MODE: When the reaction mode is set to automatic, no user
input is required for the associated task, such as adding or removing
instances, to be carried out. When the mode is set to supervised, a
runtime task that proposes one or more reactions is created. The system
administrator can approve or deny the task.
v ELASTICITY_OPERATIONS_TIMEOUT: This value defines the allotted period of
time during which a task is completed. The default value is 120 minutes.
See Configuring elasticity mode and the associated operations on page
458 for configuration details.
2. Enable overload protection. Using overload protection, you can specify
processor and memory overload protections. Processor and memory thresholds
are enforced by the Autonomic Request Flow Manager (ARFM) controller
component of Intelligent Management Pack. Processor and memory overload
protections are functions of ARFM.
a. Memory overload protection: Controls the rate at which requests without
affinity are permitted through the ODR. Use memory overload protection to
prevent Java heap utilization from exceeding a threshold that you can
specify. This option adds the heap overload protection configuration script
to the ODR. The heap overload protection configuration script can be
configured by specifying the PERCENTAGE_OF_MAXIMUM_HEAP_SIZE parameter,
which is the maximum rate ( in calls per second) that can be sustained
without exceeding the percentage of the maximum heap size.
b. CPU overload protection: Controls the rate at which requests without
affinity are permitted through the ODR. Setting the processor overload
protection prevents processor utilization from exceeding a threshold that
you can specify. This option adds the CPU overload protection
configuration script to the ODR. Configure the configuration script by
specifying the MAXIMUM_CPU_USAGE parameter.
3. Configure standard health policies. Health policies are the definitions of
specific health criteria that you want your environment to protect itself against.
Use this option to configure the following health policies:

456

IBM Cloud Orchestrator 2.4.0.2: User's Guide

a. Excessive heap usage: The excessive heap usage health policy is triggered
when memory usage exceeds the specified percentage of the heap size for a
specified time. Selecting this option adds the excessive memory usage
policy configuration script to the deployment manager part. You can
configure the excessive memory usage health policy by specifying following
script parameters:
v HEAP_USAGE_PERCENTAGE
v OFFENDING_TIME_PERIOD
v OFFENDING_TIME_UNIT: Specify the time unit in minutes.
v EXCESSIVE_MEMORY_USAGE_POLICY_REACTION_MODE
v EXCESSIVE_MEMORY_USAGE_POLICY_ACTION
v EXCESSIVE_MEMORY_USAGE_POLICY_NAME
b. Memory leak: Starts when a memory leak is detected. This policy checks if
trends, in the free memory that is available to the server in the Java heap,
decrease over time. This option adds the memory leak policy configuration
script to the deployment manager. Configure the configuration script by
specifying the following parameters:
v MEMORY_LEAK_DETECTION
v MEMORY_LEAK_POLICY_REACTION_MODE
v MEMORY_LEAK_POLICY_ACTIONS
v MEMORY_LEAK_POLICY_NAME
c. Maximum server age: Starts after an application server has been running
for a specified amount of time. This option adds the maximum server age
policy configuration script to the deployment manager. Configure the
configuration script by specifying the following parameters:
v SERVER_AGE
v SERVER_AGE_UNIT
v MAXIMUM_SERVER_AGE_POLICY_REACTION_MODE
v MAXIMUM_SERVER_AGE_POLICY_ACTIONS
v MAXIMUM_SERVER_AGE_POLICY_NAME
d. Email notification list: Specifies a list of email addresses to receive
notification when a health condition is met. This option adds the email
notification configuration script to the deployment manager. Configure the
configuration script by specifying the following parameters:
v
v
v
v
v
v

SMTP_HOST_NAME
SMTP_PORT
SMTP_USERID
SMTP_PASSWORD
EMAIL_ADDRESSES_TO_NOTIFY
SENDER_ADDRESS

4. Configure ODR-dependent health policies. Select this option when there is an

ODR in the virtual system pattern. Use this option to configure the following
health policies:
a. Maximum requests served: Starts after an application server has served a
specified number of requests. Configure the configuration script by
specifying the following parameters:
v TOTAL_REQUESTS
v MAXIMUM_REQUESTS_POLICY_REACTION_MODE
v MAXIMUM_REQUESTS_POLICY_ACTIONS
Chapter 7. Managing and deploying virtual patterns

457

v MAXIMUM_REQUESTS_POLICY_NAME
b. Excessive number of timed out requests: Starts after a specified number of
requests timeout within a 1 minute interval. Configure the configuration
script by specifying the following parameters:
v REQUEST_TIMEOUT_PERCENTAGE
v EXCESSIVE_REQUEST_TIMEOUT_POLICY_REACTION_MODE
v EXCESSIVE_REQUEST_TIMEOUT_POLICY_ACTIONS
v EXCESSIVE_REQUEST_TIMEOUT_POLICY_NAME
c. Excessive average response time: Starts when the average response time
exceeds a specified response time threshold. Configure the configuration
script by specifying the following parameters:
v EXCESSIVE_RESPONSE_TIME
v EXCESSIVE_RESPONSE_TIME_UNIT
v EXCESSIVE_RESPONSE_TIME_POLICY_REACTION_MODE
v EXCESSIVE_RESPONSE_TIME_POLICY_ACTIONS
v EXCESSIVE_RESPONSE_TIME_POLICY_NAME
d. Storm drain detection: This policy tracks requests that have a decreased
response time which has been predetermined as a significant decrease. The
actions specified for this policy are run and the associated server is restarted
when the specified detection level is reached. Configure the configuration
script by specifying the following parameters:
v STORM_DRAIN_DETECTION_LEVEL
v STORM_DRAIN_POLICY_REACTION_MODE
v STORM_DRAIN_POLICY_ACTIONS
v STORM_DRAIN_POLICY_NAME
Results
You have configured the Intelligent Management Pack advanced options for the
virtual system pattern.
What to do next
Depending on the database you are using, you can configure advanced messaging.
For more information, see Configuring advanced messaging for databases on
page 460.
Configuring elasticity mode and the associated operations:
Configure elasticity mode to add logic that causes the application placement
controller to minimize the number of nodes that are used, as well as remove nodes
that are not needed, while still meeting service policy goals. Additionally, you can
configure elasticity mode to add logic so that when the controller recognizes a
particular dynamic cluster is not meeting service policies and has started all
possible servers, the controller calls to add a node.
Before you begin
v Select the Enable elasticity mode option in the advanced options editor as
described in Configuring advanced options for Intelligent Management Pack
on page 455.
v For optimal performance, ensure that your dynamic clusters are running in
supervised mode or automatic mode. It is not recommended to have elasticity

458

IBM Cloud Orchestrator 2.4.0.2: User's Guide

mode enabled when your dynamic clusters are running in manual mode.
However, if the dynamic clusters are running in manual mode with elasticity
enabled, consider the following items:
The application placement controller does not add nodes to dynamic clusters
in manual mode.
The application placement controller does not remove nodes from dynamic
clusters in manual mode when a server is started on the specific nodes.
The application placement controller does remove nodes from dynamic
clusters in manual mode when a server is not started on the specific nodes.
v It is not recommended to use elasticity mode with uncapped mode.
v It is not recommended to enable elasticity mode when the following option is set
in the administrative console for one or more dynamic clusters: If other dynamic
clusters need resources, stop all instances of this cluster during periods of
inactivity. If you have elasticity mode enabled and the option set, the application
placement controller can remove all of the custom nodes in the cell.
v Configure certain controllers to start on the deployment manager or node agent
that will not be removed.
1. To configure the application placement controller to start on the deployment
manager, select System administration > Deployment manager > Java and
process management > Process definition > Java virtual machine > Custom
properties.
a. Enter the name of the custom property as HAManagedItemPreferred_apc.
b. Set the value of the custom property to true.
c. Click Apply, and save your changes.
d. Restart the current process in which the application placement controller
is running.
2. To configure the application placement controller to start on one of the nodes
that contains an ODR, select System administration > Nodes > node_name
> node_agent_name > Java and process management > Process definition >
Java virtual machine > Custom properties.
a. Enter the name of the custom property as HAManagedItemPreferred_apc.
b. Set the value of the custom property to true.
c. Click Apply, and save your changes.
d. Restart the current process in which the application placement controller
is running.
3. When you use elasticity mode in an environment in which multi-cell
performance management is configured, you must configure certain
controllers to start on the deployment managers of the center cell and the
point cells.
a. Set the HAManagedItemPreferred_apc custom property to true on the
deployment manager of the center cell.
b. Set the HAManagedItemPreferred_cellagent custom property to true on
the deployment manager of the point cells.
About this task
When you enable elasticity mode in the advanced options editor, the following
default actions are associated with the add and remove operations. The elasticity
operations define the runtime behaviors to monitor, and the corrective actions to
take when the behaviors are present.
1. Add virtual machine: Creates and federates a new node into the cell
Chapter 7. Managing and deploying virtual patterns

459

2. Add node to dynamic cluster action: Adds a newly-created node to the

dynamic cluster membership
3. Remove node from cell: Removes the node from the cell
4. Remove virtual machine: Removes the virtual machine from the associated
hypervisor
Complete the following procedure to define additional custom actions for the add
and remove operations.
Procedure
1. Select Operational policies > Autonomic controllers > Application placement
controller > Elasticity operation. Select the operation.
2. To add additional actions to the add operation, click Add Action... Select the
custom action from the list of Custom elasticity operation actions. If no custom
actions are defined, select Operational policies > Autonomic controllers >
Application placement controller > Elasticity Custom Actions > New.
3. To add additional actions to the Remove operation, click Add Action... Select
the custom action from the list of Custom elasticity operation actions. If no
custom actions are defined, select Operational policies > Autonomic
controllers > Application placement controller > Elasticity Custom Actions >
New.
Configuring advanced messaging for databases:
When you configure the advanced options on a cluster virtual system pattern and
you want to enable messaging, there are some additional configuration options.
You can use these options to start and use clustered messaging engines or to use a
sample authentication alias for databases.
Before you begin
See the information about working with cluster virtual system patterns that is
provided in Configuring advanced options for cluster virtual system patterns
(classic) on page 451.
About this task
To work with clustered messaging engines or configure a sample authentication
alias for databases, in certain WebSphere Application Server configurations, further
configuration is required.
Procedure
v Use the IBM Cloud Orchestrator sample authentication alias. The sample
authentication alias can be used by the messaging engines for databases other
than Derby. If you use the IBM Cloud Orchestrator messaging recommendations
and a database, for example DB2 or Oracle, perform the following steps:
1. Create the appropriate Java Database Connectivity (JDBC) driver and data
source for your database.
2. Update the sample authentication alias for the database provided by IBM
Cloud Orchestrator to contain the correct credentials to your database.
3. Change the messaging engine and SIBus configuration to use the new data
source, where the updated authentication alias is used with this data source.
v Use a database server. To correctly start and use clustered messaging engines, a
database server is required. You can use the Derby database server shipped with

460

IBM Cloud Orchestrator 2.4.0.2: User's Guide

WebSphere Application Server. IBM Cloud Orchestrator provides configuration,

the definition of a Derby database server shipped with WebSphere Application
Server, which runs on the deployment manager of the virtual system pattern. A
JDBC provider and data source point to a Derby network server. This server is
started from the deployment manager node, from the Derby installation under
the WAS installation root. IBM Cloud Orchestrator provides this function for
messaging to minimize later configuration. To start Derby from the deployment
manager before starting the messaging cluster, update the Derby configuration
for remote connections. To update this process, perform the following steps:
1. Edit the <WAS_HOME>/derby/derby.properties file. Uncomment the following
line:
#derby.drda.host=0.0.0.0

2. Start the Derby network server. To start this server, from the
<WAS_HOME>/derby/bin/networkServer/ directory run the following command:
startNetworkServer.sh | .bat

3. Start the Derby database server on the deployment manager node.

Results
You have configured the cluster virtual system pattern to start and use clustered
messaging engines or to use a sample authentication alias for databases.
What to do next
When you have configured messaging, you can configure the advanced options for
the cluster virtual system pattern you are editing.
Configuring advanced options for single server virtual system patterns (classic):
You can use the advanced virtual system pattern configuration function as a
starting point in configuring the single server virtual system pattern that defines
your cell.
Before you begin
When you open the advanced options editor for a new single server virtual system
pattern, default settings are shown for the virtual system pattern. These settings
are recommended values for the topology. To accept these default values for this
topology, click OK. To return to the virtual system pattern without setting these
default values, click Cancel.
About this task
The following options are available to further define single server virtual system
patterns:
v Enable session persistence
v Global security
Procedure
1. Enable the session persistence. HVWebCluster or application clusters are
created with associated replication domains. Therefore, you can use the hyper
text transfer protocol (HTTP) session replication. If the replication domain is
defined, no resources are started or used unless session replication is

Chapter 7. Managing and deploying virtual patterns

461

configured. You can use the Enable session persistence option and then one of
the following options to configure HTTP session persistence:
Memory-memory implemented session persistence
The HTTP session memory bit is set on all the HVWebCluster servers.
Database implemented session persistence
To use this option on the virtual system instance, the Java Database
Connectivity (JDBC) data source created must be updated on the
deployment manager. You must provide valid host, port, user name,
and password values. Also, the appropriate client drivers for your
database, for example jars and libraries, must be installed on your
WebSphere Application Server systems. IBM Cloud Orchestrator
performs the following operations:
v Creates a DB2 JDBC provider
v Creates a sample DB2 data source, with dummy values for the host,
port, ID, and password
v Sets up a session manager on each HVWebCluster server to do HTTP
session to the database, using the sample data source and dummy
connection values
For important information about suppling a database that an HTTP
session over the database supports, see Configuring database
implemented session persistence for Derby on page 463.
2. Enable global security. Using global security provides the following functions:
v Sets the global security admin bit
v Uses the WIM user registry that is provided with IBM Cloud Orchestrator
v Uses both LTPA and BasicAuth for authentication (BasicAuth is needed for
stand-alone clients)
v Uses an SSL-allowed policy for CSIv2
v Turns off single sign-on interoperability
v Configures secure file transfer between the deployment manager and the
node agents
v Enables the high availability manager to use the secure DCS channel
Use the global security option to configure secure messaging. Secure messaging
provides the following function:
v Sets the security bit on the SIBus
v Reduces the set of users that can connect to the SIBus. Only the WebSphere
Application Server ID created with the CB UI can connect. The default value
for that ID is virtuser.
v Disables the InboundBasicMessaging transport for the messaging engines
v Adds the virtuser ID to the sender role for foreign buses for MQLink
configurations
Results
You have configured the advanced options for a single server virtual system
pattern.
What to do next
You can run the wasCBUpdateSessDSInfo.py script, to configure database
implemented session persistence. For more information, see Configuring database

462

IBM Cloud Orchestrator 2.4.0.2: User's Guide

implemented session persistence for Derby.

Configuring database implemented session persistence for Derby:
Because IBM Cloud Orchestrator does not supply a database that an HTTP session
over the database supports, you must supply connection information for your
database.
About this task
An WebSphere Application Server HTTP Session over the database does not
support the use of Derby. Therefore you must supply connection information to
configure database implemented session persistence for either a cluster or single
server virtual system pattern. If you are using DB2, then you can update the
provided data source and session manager for each HVWebCluster server using
the wasCBUpdateSessDSInfo.py script.
Procedure
1. Use the wasCBUpdateSessDSInfo.py script. To configure database implemented
session persistence, run the wasCBUpdateSessDSInfo.py script using the
following parameters:
v -dbHost <host name>
v -dbPort <port number>
v -dbUser <user ID>
v -dbPassword <password of the database user>
2. Ensure that this script is in the correct directory. After the virtual system
pattern is deployed, ensure that this script is in the <WAS profile
root>/bin/DeployerScripts folder.
Results
When you have run the wasCBUpdateSessDSInfo.py script, database implemented
session persistence can be enabled.

Making virtual system patterns (classic) read-only

Either draft or read-only virtual system patterns can be deployed for testing or
production, but making a virtual system pattern read-only prevents further edits to
the topology definition. Making virtual system patterns read-only provides
consistent reuse in the cloud.

Before you begin

You must have edit access to any virtual system pattern you want to make
read-only. If it is read-only, it is already locked to editing and cannot be changed.
To make a virtual system pattern read-only, first be sure that no one with
permission to edit the virtual system pattern intends to change it.

About this task

You can make virtual system patterns read-only if you want to prevent further
editing to the virtual system pattern.

Chapter 7. Managing and deploying virtual patterns

463

Procedure
1. From the left panel of the Virtual System Patterns (Classic) window, select the
virtual system pattern. Virtual system patterns that have the read-only symbol
by them are already read-only and cannot be edited. Virtual system patterns
with the edit symbol beside them are not read-only and can be edited. Basic
information about the selected virtual system pattern is shown in the right
panel of the Virtual System Patterns (Classic) window.
2. Determine if you are ready to lock editing of the virtual system pattern.
v If virtual system pattern editing is complete and you are ready to make the
virtual system pattern read-only, click the Lock icon in the upper right
toolbar of the Virtual System Patterns (Classic) window.
v If virtual system pattern editing is not complete, see the information in
Editing a virtual system pattern (classic) on page 442 and Configuring
advanced options on page 449.
3. Verify that you want to make the virtual system pattern read-only. When
prompted to verify that you want to make the virtual system pattern read only,
click OK to lock the virtual system pattern.

Results
When you have made the virtual system pattern read-only, it can be cloned or
deleted but it cannot be edited.

What to do next
You can deploy the virtual system pattern to the cloud. For more information, see
Deploying a virtual system pattern (classic).

Deploying a virtual system pattern (classic)

You can deploy virtual system patterns to run in a cloud group. You can deploy
either draft or committed virtual system patterns for testing or production.

Before you begin

Configure the virtual system pattern, including the advanced configuration, and
ensure that it is ready to be deployed. See Editing a virtual system pattern
(classic) on page 442 and Configuring advanced options on page 449 for more
information.
When a virtual system provisioning is requested by a user in a project and
targeted to an environment profile that maps to an OpenStack region, the quota
limitations are checked in the following sequence:
1. Workload Deployer checks that the requested capacity fits the environment
profile quota.
2. OpenStack checks that the required capacity fits the user's project quota.
If both checks are passed, then the virtual system deployment is performed. To
modify quotas on OpenStack, refer to Configuring project quotas on page 268.
To modify quotas in the environment profile, refer to Creating an environment
profile on page 355.

About this task

This task describes deploying a virtual system pattern to run in the cloud group.

464

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. From the list in the left panel of the Virtual System Patterns window, select the
virtual system pattern to deploy.
2. Indicate that you want to deploy the virtual system pattern. Click the Deploy
icon on the upper right panel of the Virtual System Patterns (Classic) window.
3. Provide the necessary information. The Describe the virtual system instance
you want to deploy dialog provides the fields of information to deploy the
virtual system pattern to the cloud. The parameters that are required differ
depending on any advanced configuration you have defined and any
associated script packages you have included. Links to the advanced
configuration and the scripts are provided on the interface. Provide the
following information to deploy the virtual system pattern:
Virtual system instance name
Enter the name of the virtual system instance in which to deploy this
virtual system pattern.
Choose Environment
You can deploy the virtual system pattern using an environment
profile. Make your selections from the following options:
IP version
IPv4 is selected. IPv6 is not currently supported.
Choose cloud group
This option is not currently supported.
Choose profile
Select this option to deploy the virtual system pattern using an
environment profile. Then select the environment Type and a
valid environment Profile from the lists.
Note: If the Pattern deployer option was chosen, you cannot
specify an IP address that is contained within the IP groups
which are defined in IBM Cloud Orchestrator.
Note: IBM Cloud Orchestrator is not able to filter environment
profiles suitable for deployment to VMware clusters based on
the images contained in the virtual system pattern that you are
deploying. Make sure you are selecting a valid environment
profile.
For more information about environment profiles, see Managing
environment profiles on page 354.
Schedule deployment
Click this link to provide information about when the virtual system
pattern is to be deployed and for how long. You can deploy the virtual
system pattern immediately after providing the information in the
dialog or you can schedule deployment using the following options:
Start now
Deploys the virtual system pattern immediately after providing
the required information in the dialog. Start now is the default
option.
Start later...
Provide the date and time to deploy this virtual system pattern
at a later time.
Chapter 7. Managing and deploying virtual patterns

465

Run indefinitely
Runs this virtual system pattern continuously. Run indefinitely
is the default option.
Run until...
Use this option to provide the end date and time for the virtual
system pattern to stop running.
Configure parts
For each virtual image part requiring information, click the link and
provide the information for each configuration parameter shown. The
set of parameters depends on the part itself. The parts that require
information are different depending on the type of virtual image to be
deployed and the type of hypervisors in the cloud. For example, parts
for an WebSphere Application Server image would require different
information than parts for a DB2 image.
Note: The administrator password that you specify for a Windows
virtual image must meet complexity requirements (for example,
Passw0rd).
Note: The WebSphere administrative user name should be non-root
user only.
Note: If you are using a non-English operating system, you must
specify the correct language and country in the Default Locale and
Default Country parameters to correctly deploy the virtual image.
For virtual image parts, you must specify a value in the Flavor field. In
OpenStack, the instance flavor describes the memory and storage
capacity of the virtual machine to be deployed. By default the flavor
values are:
m1.tiny
Memory: 512 MB, vCPUs: 1, Storage: 0 GB
m1.small
Memory: 2048 MB, vCPUs: 1, Storage: 20 GB
m1.medium
Memory: 4096 MB, vCPUs: 2, Storage: 40 GB
m1.large
Memory: 8192 MB, vCPUs: 4, Storage: 80 GB
m1.xlarge
Memory: 16384 MB, vCPUs: 8, Storage: 160 GB
Note:
v The flavor values might change depending on the configuration of
your OpenStack environment. In OpenStack, use the nova
flavor-list command to view the list of available flavors and their
characteristics.
v The 0 GB storage size is a special case which uses the native base
image size as the size of the ephemeral root volume. When you use a
flavor with 0 GB of storage, no automatic check is performed by
OpenStack on available storage capacity. You must ensure that there
is sufficient storage to contain the provisioned VM image disks.

466

IBM Cloud Orchestrator 2.4.0.2: User's Guide

To ensure that proper storage capacity check is performed by

OpenStack, use flavors that specify storage size greater than zero and
larger than the image disk size. Note that on VMware the image uses
IDE driver. Then, VMware cannot perform disk expansion and the
flavor storage size must match the disk size of the provisioned image
or specify disk=0.
v To understand what memory, CPU and disk size should be used
while creating a new flavor, see Managing flavors on page 100.
v Only flavors that are suitable for the selected images are displayed.
For information about changing the virtual machine flavor after
deploying the virtual system pattern, see Virtual machine panel fields
on the Virtual System Instances (Classic) window on page 488.
If the information for each of these virtual image parts is provided, a
green check mark is shown to the left of the virtual image part. If there
is information missing for one of these virtual image parts, the check
box to the left of it does not contain a green check mark. In this case,
click the virtual image part missing information and provide that
information in the fields shown.
If you are using an environment profile there might be additional fields
to configure for the parts. If the environment profile specifies that the
virtual system pattern deployer is to provide the IP address, the IP
addresses must also be provided for the parts. Specify the following
part information:
In cloud group
Select the cloud group as you normally would. If an alias was
provided to define the cloud group in the environment profile,
then the alias name is available to be selected in this field.
IP Group
Select an IP group as you normally would. If an alias was
provided to define the IP group in the environment profile,
then the alias name is available to be selected in this field.
Addresses:
Provide both the host name and the IP address. The host name
and IP address must not exist in the selected IP group.
If you are deploying parts with add-ons, you can configure fields for
those add-ons if they were not configured when the part was created
and locked to editing during deployment.
4. Deploy the virtual system pattern. When all of the information is provided
correctly in the dialog, click OK to deploy the virtual system pattern.

Results
The virtual system pattern is deployed to the cloud and runs in the selected virtual
system instance.
On a topology deployment, some parts can reserve CPU or memory, or both. These
fields effect how the CPU and memory are configured on the underlying
hypervisor. The CPU and memory limits are set and reserved for ESX hypervisors.
This setting prevents the CPU from being overcommitted but reduces license
usage.

Chapter 7. Managing and deploying virtual patterns

467

What to do next
To add additional nodes to the virtual system pattern, first stop the virtual system
in which the cloud the virtual system pattern is deployed to is running. For more
information about virtual system instances, see Managing virtual system instances
(classic) on page 476.
Deploying a pattern (classic) with additional actions:
You can deploy a virtual system pattern with additional configuration options that
were previously defined in Business Process Manager.
Procedure
1. From the list in the left panel of the Virtual System Patterns (Classic) window,
select the virtual system pattern to deploy.
2. Click the Deploy in the cloud icon on the upper right panel of the Virtual
System Patterns (Classic) window. A popup window opens with a set of
deployment options and parameters that you can configure.
3. Select options for the virtual system that you want to deploy. For information
about specific settings, see Deploying a virtual system pattern (classic) on
page 464.
4. If actions with user interface are defined on this pattern, a Configure actions
section is available. Click the link to view all actions that must be configured.
5. Click the action that you want to configure, and submit any required
parameters. A green checkmark is displayed next to the action name.
6. Repeat the previous step for all other actions that require configuring.
7. When all of the information is provided correctly in the dialog, click OK to
deploy the virtual system pattern.

Deleting a virtual system pattern (classic)

You can delete any virtual system patterns you own using the IBM Cloud
Orchestrator user interface.

Before you begin

You must be the owner of a virtual system pattern you want to delete.

About this task

You can delete a custom virtual system pattern if the access control lists (ACLs)
permit you to do so.

Procedure
1. From the list of virtual system patterns in the left panel of the Virtual System
Patterns (Classic) window, select the virtual system pattern to delete. If the
virtual system pattern is not shown, you can also search for a virtual system
pattern using the search function. Basic information about the selected virtual
system pattern is shown in the right panel of the Virtual System Patterns
(Classic) window.
2. Determine if you are ready to delete the virtual system pattern.
v If you are ready to delete the virtual system pattern, click the delete icon in
the upper right toolbar of the Virtual System Patterns window.

468

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v If you want to change the virtual system pattern instead of deleting it, see
the information in Editing a virtual system pattern (classic) on page 442
and Configuring advanced options on page 449.
3. Verify that you want to delete the virtual system pattern. When the prompted
to verify that you want to delete the virtual system pattern, click OK.

Results
You return to the Virtual System Patterns (Classic) window and the virtual system
pattern has been deleted and is no longer shown in the list on the left panel.

Virtual system pattern (classic) windows

The Virtual System Patterns (Classic) and Pattern Editor windows provide fields to
view and work with your virtual system pattern topology. Virtual system patterns
contain parts, scripts, and add-ons that you can graphically add and edit to
customize your topology.
There are two interactive windows for working with virtual system patterns:
v The Virtual System Patterns (Classic) window provides the following interactive
panels:
Left panel
The left panel of the Virtual System Patterns (Classic) window lists the
virtual system patterns available for the virtual images. You can also use
this panel to search for or add new virtual system patterns.
Right panel
The right panel of the Virtual System Patterns (Classic) window shows
information, including the topology, about a virtual system pattern you
select from the list on the left.
For information about the fields on the Virtual System Patterns (Classic)
window, see Fields on the Virtual System Patterns (Classic) window on page
470.
v The Pattern Editor window provides the following interactive panels:
Left panel
When a specific virtual system pattern is being edited, the Pattern Editor
panel provides lists of scripts, parts, and add-ons that can be added to
the virtual system pattern topology.
Right panel
Virtual system pattern parts, scripts, and add-ons associated with the
parts can be edited graphically on this canvas.
For more information about the fields on the Pattern Editor window, see Fields
on the Pattern Editor window on page 472.

Chapter 7. Managing and deploying virtual patterns

469

Fields on the Virtual System Patterns (Classic) window:

The IBM Cloud Orchestrator Virtual System Patterns (Classic) window lists the
virtual system patterns you have configured and provides fields to view and work
with your topology. The Virtual System Patterns (Classic) window graphically
shows the parts, scripts, and add-ons in your topology.
There are two interactive panels of the Virtual System Patterns (Classic) window.
The virtual system patterns are listed in the left panel. Configuration and topology
information for a selected virtual system pattern is displayed in the right panel.
Virtual system patterns list
The left panel of the Virtual System Patterns (Classic) window provides a list of
virtual system patterns to work with. Virtual system patterns that have the
read-only symbol beside them are read-only and cannot be edited. To work with
one of these virtual system patterns, it must be cloned and then the clone can be
edited. Virtual system patterns in the list that have the draft symbol beside them
can be edited directly.
An Add icon at the top of the window adds a new virtual system pattern. See
Creating a virtual system pattern (classic) on page 440 for more information. A
search and sort function searches for virtual system patterns not listed and sorts
through the list of virtual system patterns that are found.
Icons on the Virtual System Patterns (Classic) window
The following icons are on the upper right top bar:
Refresh
Refreshes the virtual system pattern display in the configuration panel
after any changes, such as editing or deployment.
Deploy
Deploys the virtual system pattern to the cloud group you specify. This
icon is available when the virtual system pattern contains at least one
virtual part. Click it to specify the cloud group and deploy the virtual
system pattern. See Deploying a virtual system pattern (classic) on page
464 for more information about deploying virtual system patterns.
Edit

This icon is available if the virtual system pattern is not read-only and can
be edited. See Editing a virtual system pattern (classic) on page 442 for
more information.

Clone Clones the selected virtual system pattern. Cloning a virtual system pattern
is useful if the virtual system pattern is read-only and cannot be edited.
This option is available for the predefined virtual system patterns that are
provided by IBM and any virtual system patterns that are created and
locked to editing. You can clone the virtual system pattern and then edit
and deploy the copy. See Cloning an existing virtual system pattern
(classic) on page 438 for more information about cloning virtual system
patterns.
Lock

Locks the virtual system pattern to editing, making it read-only. See

Making virtual system patterns (classic) read-only on page 463 for more
information.

Delete Deletes the virtual system pattern from IBM Cloud Orchestrator. See

470

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Deleting a virtual system pattern (classic) on page 468 for more

information about deleting virtual system patterns.
Fields on the right configuration panel
Selecting a virtual system pattern in the left panel of the Virtual System Patterns
(Classic) window displays the basic virtual system pattern properties in the right
panel. The name of the selected virtual system pattern is displayed on the top bar
of the right panel.
The following fields are available to specify and view some details about a virtual
system pattern:
Description
An editable field that provides the description of the virtual system
pattern. This description can help identify the virtual system pattern to
other users who have been provided access to it.
Created on
Provides the time stamp when the virtual system pattern was created.
Current status
Provides the status of the virtual system pattern:
Draft

For any virtual system pattern you are creating, the initial status is
Draft.

Locked (read only)

This field shows if the virtual system pattern is read only. Virtual
system patterns can be made read only by clicking the lock icon on
the top of the right panel.

Updated on
The timestamp of the most recent update.
In the cloud now
When the virtual system pattern is in use, this field shows the names of
the virtual system instances currently running that were created from this
virtual system pattern. Until you run the virtual system pattern in a cloud,
this field displays (none) initially.
Access granted to
This field can be edited and it provides access to this virtual system
pattern for other projects. Selecting projects, makes the virtual system
pattern readable or writable to the users belonging to these projects.
Initially this field is set to the role of the owner of the virtual system
pattern.
By default, the Add more box contains the Everyone built-in project. When
a project has been added, click the link beside the entry to toggle between
the following access levels:
v Read
v Write
v All
Click the link name of the project to show information about that project.
You can also click the remove link to remove access for a project.

Chapter 7. Managing and deploying virtual patterns

471

Topology for this pattern

Displays any warnings or errors. This section of the panel provides a
graphical representation of the topology.
Hypervisor type
Displays a message providing the type of hypervisor to which the
virtual system pattern deploys.
Graphical topology
Provides a graphical display of the parts that make up the virtual
system pattern. For WebSphere Application Server virtual system
patterns, the parts in the topology can vary, depending on the
virtual images you have installed.
To see the virtual image and operating system information for
parts on the editing palette, hover your cursor over the part to
display a pop-up window that provides this information.
Comments
Displays any comments that have been added to the virtual system
pattern and provides a free form space to add comments.
For information about the Pattern Editor window, see Fields on the Pattern Editor
window.
Fields on the Pattern Editor window:
The IBM Cloud Orchestrator Pattern Editor window contains lists of parts, scripts,
and add-ons to graphically work with your topology. You can use these parts,
scripts, and add-ons to edit and customize your virtual system pattern topology
and, therefore, your deployment.
When a virtual system pattern is edited, using the edit icon in the Virtual System
Patterns (Classic) window, the Pattern Editor window opens for that virtual system
pattern. There are two interactive panels of the Pattern Editor window. The parts,
scripts, and add-ons are listed in the left panel. The right panel is a virtual system
pattern editor canvas for that specific virtual system pattern. The search function is
available for parts, scripts, or add-ons.
Parts, scripts, and add-ons panel
The Parts, Scripts and Add-Ons lists are available in the left panel of the Pattern
Editor window.
Parts

The Parts list displays the parts available to use in your virtual system
pattern. The parts that are available depend on the virtual images you
have installed and the hardware type of any parts already in the virtual
system pattern. Only parts with the same hardware type as any parts
already in the virtual system pattern are available. When you select parts
in the Parts list, parts are then displayed. You can select them and drop
them onto the canvas on the right side of the Pattern Editor.

Scripts
The Scripts list provides the script packages that are available. This list can
contain any script packages that you have provided for use with IBM
Cloud Orchestrator. You can add script packages to the parts on the editing
palette. Add parts by dragging them onto the workspace on the right
canvas of the Pattern Editor window and dropping them onto the part
objects.

472

IBM Cloud Orchestrator 2.4.0.2: User's Guide

For more information about script packages, see Adding a script package
on page 367 and Associating a script package with a pattern on page
371.
Add-Ons
The Add-Ons list provides the add-ons that are available. This list can
contain any add-ons that you have provided for use with IBM Cloud
Orchestrator. You can add add-ons to the nodes on the editing palette. Add
the add-ons by dragging them onto the workspace on the right canvas of
the Pattern Editor window and dropping them onto the node objects. The
following types of add-ons can be added to the nodes:
Disk

Add a disk to a node for deployment on a virtual machine.

NIC

Add a NIC, or multiple NICs, to a node for deployment on a

virtual machine.

User

Add a user, or multiple users, to a node for deployment on a

virtual machine.

For more information about add-ons, see Adding add-ons to the catalog
on page 411.
See Virtual system pattern (classic) editing views and parts on page 443 for more
information about the interaction of these parts on the canvas.
Available views
When a specific virtual system pattern is being edited in the Editor window, the
graphical topology view is displayed in an editing canvas. There are two options
to view a virtual system pattern on the editing canvas that are provided by toggle
links at the top right of the page:
Ordering
This link changes the view to show the order the parts are started when
the virtual system pattern is deployed. If you are working with a copy of a
provided virtual system pattern, there is a recommended order and this
order is the default setting. In this view, the parts are shown in the right
column of the panel and numbered in the order they are started. The left
column provides a textual description of the order in which the parts are
started with order constraints for parts and scripts.
Topology
This link is shown when you are in the Ordering view. Click it to switch
back to the topology view in which the relationship of the parts is shown.
Icons and links
From either the Topology or Ordering view, the following icons and links are on
the upper right of the panel:
Refresh
Forces a refresh of the virtual system pattern to ensure that the diagram
shows the current state of the virtual system pattern in IBM Cloud
Orchestrator. Refreshing the virtual system pattern is useful if, for example,
the virtual system pattern has been edited by another user since it was last
retrieved by the web browser.

Chapter 7. Managing and deploying virtual patterns

473

Undo

Undo the previous action. The virtual system pattern is saved during the
editing process, so use this option to back up to the state of the virtual
system pattern before the last edit.

Undo all
Undo all changes made in the current editing session for this virtual
system pattern. The virtual system pattern is saved during the editing
process, so use this option to back up to the state of the virtual system
pattern before all edits were made during the current editing session.
Done editing
Indicates that you have finished editing and returns to the initial view of
the virtual system pattern.
Advanced options
This link opens a configuration window for the virtual system pattern you
are editing. The configuration window contains options that are available
for this virtual system pattern. A set of default options are selected. These
are common choices for topology virtual system patterns like the one you
are editing. For more information about advanced options, see
Configuring advanced options on page 449.
Fields on the topology configuration panel
The graphical editing canvas, on the right panel of the Pattern Editor window
provides an interactive graphical display of parts. These parts, scripts, and add-ons
make up the topology of the virtual system pattern. Parts displayed on the left
panel can be added to the canvas and the parts on the canvas can be manipulated.
The parts available can vary, depending on the virtual images you have installed.
Available parts might include the following objects:
v Administrative agent
v Custom node
v Deployment manager
v
v
v
v

IBM HTTP Server

Job manager
Stand-alone server
On-demand router

Hovering your cursor over the part label displays a window that provides
additional information about the part and its virtual image. The following actions
can be performed:
v Drop parts onto the palette from the Parts list
v Edit the properties for the parts on the palette (using the edit properties icon on
the part, to open a properties panel)
v Drop scripts or add-ons onto the parts from the Scripts and Add-Ons lists
v Edit parameters, if the script has parameters, using the edit properties icon.
v Change the count for some types of parts
v Lock the count
v Delete a part
v Change a part so that it comes from a different virtual image
v Delete scripts or add-ons

474

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Virtual system pattern (classic) processing

When deploying a virtual system instance, that is a collection of virtual machines,
IBM Cloud Orchestrator virtual system pattern processing follows a specific startup
sequence.
A virtual system pattern is one or more virtual images and applications from the
IBM Cloud Orchestrator catalog that implements a deployment topology.
When deploying a virtual system instance, a collection of virtual machines, it is
helpful to understand the startup sequence that IBM Cloud Orchestrator virtual
system pattern processing follows. The following sequence shows this order:
1. Virtual machines (defined by the virtual image parts) are started, to the extent
possible, concurrently. Virtual image parts might have a dependency on other
parts when cross configuration takes place as part of the virtual machine
startup. See Virtual system pattern (classic) editing views and parts on page
443 for details about dependencies between virtual image parts. In such cases,
the dependent virtual machines are started second. For example, in a
WebSphere Application Server virtual system pattern, a deployment manager is
started before any custom nodes. The custom nodes can be started either
sequentially or concurrently with each other, depending on the image.
WebSphere Application Server 6.1.0.25 custom nodes are started sequentially,
for example, and WebSphere Application Server 7.0.0.5 nodes are started
concurrently.
2. When the virtual machines are activated, custom nodes are federated by the
deployment manager in the topology. If both stand-alone nodes and a
deployment manager are in the topology, the stand-alone nodes are federated
by the deployment manager. In addition, administrative agents and deployment
managers are registered with a job manager if one is present in the topology.
3. Add-ons defined for each of the virtual machines are run.
4. The advanced setting scripts, provided by IBM that define the system
configuration, run. This set of supplied scripts define settings like HTTP session
clustering properties and security.
5. Script packages for each of the virtual machines are run. If a virtual system
pattern specifies multiple script packages for the same virtual machine, the
script packages are run in the order they were added to the virtual system
pattern.
As an example, if you are deploying a virtual system pattern with a deployment
manager and two custom nodes, the following processing occurs:
1. The deployment manager virtual machine and the deployment manager profile
are started.
2. The first custom node virtual machine is started and the custom node profile is
federated.
3. The second custom node virtual machine is started and the custom node profile
is federated.

Chapter 7. Managing and deploying virtual patterns

475

Managing virtual system instances (classic)

A virtual system instances is the virtual environment that is being managed by
your IBM Cloud Orchestrator.

Before you begin

You must specifically be granted access to the virtual system instances or be
assigned the admin role to perform these steps.

About this task

Virtual system instances are create when you deploy virtual images or use patterns
composed of parts that are provided in your virtual images. The virtual images
and the patterns are deployed to your hypervisors based on a component of IBM
Cloud Orchestrator called placement. The internal placement component performs
the job of deciding which hypervisors to use when deploying virtual machines.
The placement component is also used when an existing virtual system instances is
extended by adding virtual machines. It uses a complicated algorithm that
considers a number of properties of the environment. For example, it considers the
properties of the physical machines, existing virtual system instances on the
hypervisors, and virtual machines on the hypervisor not managed by IBM Cloud
Orchestrator. The properties of the virtual system instances being deployed or
extended are also considered when making placement decisions. Most notably, the
placement component considers the memory, physical CPUs, network addresses,
disk space, and disk image sharing on the hypervisor. The placement component is
part of the product code and is not configurable.
The virtual system instances are managed by IBM Cloud Orchestrator and can be
serviced and accessed through the user interface. Virtual system instances managed
by IBM Cloud Orchestrator are dynamic. Virtual machines can be added or
removed to allow your virtual systems to scale based on current demand. If
needed, you can scale down the environment and remove unnecessary virtual
machines.

Procedure
You can use the user interface to manage your virtual system instance. See
Managing virtual system instances (classic) with the user interface for more
information.

Results
You have become familiar with all the actions associated with managing a virtual
system instances.

Managing virtual system instances (classic) with the user

interface
You can manage your IBM Cloud Orchestrator virtual system instances with the
user interface.

Before you begin

You must specifically be granted access to the virtual system instance you intend
to start or be assigned the admin role to manage your virtual system instances. To
create a virtual system instance, you must deploy a pattern into the cloud. See
Deploying a virtual system pattern (classic) on page 464, for more information

476

IBM Cloud Orchestrator 2.4.0.2: User's Guide

about creating a virtual system instance by deploying a pattern.

About this task

You can perform a variety of tasks to manage your IBM Cloud Orchestrator virtual
system instances with the user interface.
Note: Creating, restoring, or deleting snapshots for virtual system instances is not
available on Power instances.
Note: When deploying instances to a VMware region, the name specified at
deployment time is propagated from the Self-service user interface to the
OpenStack component. The instance is created in the VMware hypervisor using the
corresponding OpenStack UUID. To match an instance in OpenStack with the
actual instance deployed on VMware, complete the following steps:
1. On the Region Server where the deployment occurred, run the nova list
command and identify the instance UUID in the command output.
2. In the vCenter client, in the search field, type the instance UUID and press
Enter.

Procedure
1. Navigate to the Virtual System Instances (Classic) window by clicking
PATTERNS > Instances > Virtual System Instances (Classic) from the menu
bar.
The list of the virtual system instances being managed by IBM Cloud
Orchestrator is displayed along with the status of each virtual system instance.
This list provides an overview of the existing virtual system instances but most
management functions for these virtual system instances require you to select a
specific virtual system instance.
2. Select a specific virtual system instance to manage by clicking a
<virtual_system_name> from the list of the virtual system instances. The
details for the virtual system instance you selected are displayed. If you want
to manage a different virtual system instance, then click a different
<virtual_system_name> and the associated virtual system instance details are
displayed.
3. You can perform the following tasks with virtual system instances:
v Start an existing virtual system instance. Virtual system instances managed
by IBM Cloud Orchestrator are not always running and in the started state.
When a virtual system instance is in the stopped state, you can restart the
virtual system instance to redeploy the virtual system instance into the cloud.
v Stopping a persistent virtual system instance (classic) on page 479. Virtual
system instances can be stopped without removing the virtual system
instance from IBM Cloud Orchestrator. If a virtual system instance is
stopped, then the virtual system instance is not running, but management of
the virtual system instance is retained by IBM Cloud Orchestrator and the
virtual system instance remains available for redeployment in the future.
v Removing a virtual system instance (classic) on page 480. You can remove
a virtual system instance when it is no longer needed. By removing a virtual
system instance, you release all the IBM Cloud Orchestrator resources,
making them available for placement decisions.

Chapter 7. Managing and deploying virtual patterns

477

v Creating a snapshot image on page 481. You can create a snapshot image
to store the current state of the virtual system instance. You can later use this
snapshot image to partially restore your virtual system instance to the stored
state.
v Restoring virtual system instances (classic) from a snapshot image on page
482. A snapshot image represents a previously captured state of the virtual
system. Using this snapshot image, you can restore the state of virtual
machines that were present in the virtual system instance to their stored state
at the time the snapshot was taken.
v Deleting snapshot images on page 483. You can delete a snapshot image of
a virtual system instance that you no longer require.
v Accessing virtual machines in your virtual system instance (classic) on
page 485. Each virtual system instance consists of a set of virtual machines
that represent a physical node in an application server environment. You can
access the individual virtual machines that make up your virtual system
instance from the IBM Cloud Orchestrator user interface.
v Viewing the details for your virtual machines on page 487. Each virtual
system instance consists of a set of virtual machines that represent a physical
node in an application server environment. The details of each of these
virtual machines can be viewed and monitored from the panel displaying the
details for the virtual system instance.

Results
After you have followed these steps, your virtual system instance is ready to be
used.
Starting a persistent virtual system instance (classic):
Virtual system instances managed by IBM Cloud Orchestrator are not always
running and in the started state. When a persistent virtual system instance is in
either the stopped state or the stored state, you can restart the virtual system
instance to redeploy the virtual system instance into the cloud.
Before you begin
You must specifically be granted access to the virtual system instance you intend
to start or be assigned the admin role to perform these steps. These steps are only
intended for starting a virtual system instance that is in the stopped state or the
stored state. To create a virtual system instance, you must deploy a pattern into the
cloud. See Deploying a virtual system pattern (classic) on page 464, for more
information about creating a virtual system instance by deploying a pattern.
About this task
When a virtual system instance is stopped, the IBM Cloud Orchestrator resources
are not released and the virtual system instance remains managed by IBM Cloud
Orchestrator. The virtual system instance still has an impact on placement
decisions though it is not actively running on the hypervisor. The IBM Cloud
Orchestrator resources assigned to this virtual system instance are maintained to
ensure that IBM Cloud Orchestrator resources are available when the virtual
system instance is restarted.
If your virtual system instance has been stored, then other virtual system instances
might have consumed the memory required to restart your virtual system instance.

478

IBM Cloud Orchestrator 2.4.0.2: User's Guide

If this scenario occurs, then you can stop and then store other virtual system
instances to release sufficient memory to ensure that your stored virtual system
instance can be restarted. Follow these steps to redeploy the virtual system
instance into the cloud by restarting the virtual system instance.
Procedure
From the Virtual System Instances window, click the start icon to deploy the
virtual system instance in to the cloud. Deployment of the virtual system instance
into the cloud does not happen instantly. The deployment time depends on the
virtual system instance size and the system activity. The starting icon is displayed
while the deployment process is in progress or all the virtual machines in a cluster
have not yet started. When the state of the virtual system instance is The virtual
system has been deployed and is ready to use, then the virtual system instance is
running in the cloud and available for use. The failed icon is displayed if the
virtual system instance does not start successfully.
Results
Your virtual system instance is started and ready to be used.
What to do next
You can now access and use your virtual system instance. See Accessing virtual
machines in your virtual system instance (classic) on page 485 for more
information.
Stopping a persistent virtual system instance (classic):
You can stop a persistent virtual system instance without removing the virtual
system instance from IBM Cloud Orchestrator. If you stop a virtual system
instance, the virtual system instance is not running, but management of the virtual
system instance is retained by IBM Cloud Orchestrator and the virtual system
instance remains available for redeployment in the future.
Before you begin
You must specifically be granted write or all access to the virtual system instance or
be assigned the admin role to perform these steps.
About this task
When you stop a persistent virtual system instance, the resources are not released.
A stopped virtual system instance still affects placement decisions even though it is
not actively running on the hypervisor. The resources assigned to this virtual
system instance are maintained to ensure that the resources are available when you
redeploy the virtual system instance in to the cloud. Follow these steps to redeploy
the virtual system instance in to the cloud by starting the virtual system instance.
Procedure
From the Virtual System Instances window, click the stop icon to stop your virtual
system instance. Stopping the virtual system instance does not happen instantly.
When the state of the virtual system instance is Stopped, then the virtual system
instance has finished stopping. All virtual machines are stopped when a virtual
system instance is stopped. If you must stop only certain virtual machines, then
Chapter 7. Managing and deploying virtual patterns

479

this can be achieved using the associated virtual machine actions. Stopping a
virtual system instance does not release the associated resources. When a virtual
system instance is stopped, clicking the start icon restarts the virtual system
instance using the resources it had reserved.
Results
Your virtual system instance is no longer running but remains available for
redeployment in the future.
What to do next
Create a virtual system instance by deploying a pattern or access a different virtual
system instance that is started. See Deploying a virtual system pattern (classic)
on page 464 and Accessing virtual machines in your virtual system instance
(classic) on page 485 for more information.
Removing a virtual system instance (classic):
You can remove a virtual system instance when it is no longer needed. By
removing a virtual system instance, you release all the cloud resources, making
them available for placement decisions.
Before you begin
You must specifically be granted all access to the virtual system instance or be
assigned the admin role to perform these steps.
About this task
When a virtual system instance is stopped, the cloud resources are not released.
The processor usage and the memory allocation associated with the virtual system
instance effects placement decisions made by IBM Cloud Orchestrator. Though the
virtual system instance is not actively running, placement decisions are still
effected. The cloud resources assigned to this virtual system instance are
maintained to ensure that they are available if the virtual system instance is
redeployed into the cloud. Deleting the virtual system instance releases the
resources and the virtual system instance are no longer a factor in placement
decisions. Follow these steps to remove the virtual system instance from IBM
Cloud Orchestrator.
Procedure
1. From the Virtual System Instances window, click the remove icon to remove the
virtual system instance and release the IBM Cloud Orchestrator resources.
Clicking the remove icon displays a window requesting confirmation that this
virtual system can be deleted.
2. In the confirmation dialog, specify what you want to delete.
Delete the virtual system instances history and log files as well.
When deleting a virtual system instance, you can delete history
information and logs from that virtual system instance. To retain this
information, ensure that the Delete the virtual system instances
history and log files as well check box is not selected in the dialog
box.

480

IBM Cloud Orchestrator 2.4.0.2: User's Guide

If this virtual system instance contains any scripts that are run at
virtual system instance deletion, the check box must be
disabled. Otherwise, you cannot see the logs from the run of that
script.
Note: Scripts run at virtual system instance deletion are only run if the
virtual system instance is running when it is deleted.
Ignore errors on delete.
When deleting a virtual system instance, you are also presented the
option to ignore any errors that occur with the deletion. If you attempt
to delete a virtual system instance and all associated virtual machines
cannot be deleted, the delete fails. You can use the Ignore errors on
delete option to force deletion of the virtual system instance.
CAUTION:
This option is helpful in specific situations only, so use this option
with caution. You might know that the virtual machines cannot be
deleted and you choose to clean them up manually, for example. Or,
you might know that the server that is hosting the virtual machine is
no longer available. Therefore, the delete would not occur because
the errors would block the delete. You can use the Ignore errors on
delete check box in these circumstances to force deletion of a virtual
system instance, even if the virtual machines cannot be deleted.
3. Click OK to delete the virtual system instance with the parameters you
specified.
Results
After you have followed these steps, the virtual system instance has been removed
from the cloud.
What to do next
You can create a virtual system instance by deploying a pattern or you can access
any virtual system instance that is already started. See Deploying a virtual system
pattern (classic) on page 464 for more information about creating a virtual system
instance by deploying a pattern. See Accessing virtual machines in your virtual
system instance (classic) on page 485 for more information about accessing a
virtual system instance.
Creating a snapshot image:
You can create a snapshot image to store the current state of the virtual system
instance (classic). You can later use this snapshot image to partially restore your
virtual system instance to the stored state.
Before you begin
You must be granted access to the virtual system instance or have the admin role
to complete this task.
Note: The snapshot operation is supported only for VMware, and takes a snapshot
only of the disk image, without preserving memory state. This functionality is
consistent with the OpenStack model of snapshots.

Chapter 7. Managing and deploying virtual patterns

481

About this task

Using the snapshot function, you can store the state information for each of the
virtual machines in the virtual system instance as it is running. You can use this
snapshot image to restore these virtual machines in the virtual system instance to
the states that existed when the snapshot was taken. Be aware of the following
conditions:
v By restoring the virtual system instance using a snapshot image, the current
state of the virtual system instance is lost.
v You can create only one snapshot image for each virtual machine.
v When you create a snapshot image for a virtual system instance that already has
a snapshot image stored, the existing snapshot is removed.
v Any virtual machines that are added to the virtual system instance after the
snapshot image is taken are still present after restoring the virtual system
instance to its previously stored state.
Procedure
1. Click PATTERNS > Instances > Virtual System Instances (Classic).
2. Select the virtual system instance for which you want to create a snapshot.
3. Click Create to take a snapshot image of the current state of the selected virtual
system instance. The virtual system instance status becomes Snapshooting until
the snapshot image is completed. When the snapshot is successfully created, it
is listed under the Create and the Restore buttons.
4. Optional: You can add a description for the snapshot image by clicking
Snapshot Description and entering your text. Then click Enter to store the
description.
Results
After completing these steps, you have a snapshot image available to restore the
state of the virtual machines in the virtual system instance to their stored state.
Any virtual machines that are added after the snapshot image is taken are
unaffected by the restore operation.
What to do next
You can continue working with your virtual system instance, and if needed at
some later time, you can restore your virtual system instance using the snapshot
image.
Restoring virtual system instances (classic) from a snapshot image:
A snapshot image represents a previously captured state of the virtual system.
Using this snapshot image, you can restore the state of virtual machines that were
present in the virtual system instance to their stored state at the time the snapshot
was taken.
Before you begin
You must be granted access to the virtual system instance or have the admin role
to complete this task.

482

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

Using the snapshot restore function, you can restore the state information for each
of the virtual machines in the virtual system instance to their state when the
snapshot was taken. When you restore a virtual system instance by using a
snapshot image, the current state of the virtual system instance is lost.
Any virtual machines in the virtual system instance that were added after the
snapshot image was taken are still present and are unaffected when you restore the
virtual system instance to its previous state.
Procedure
1. Click PATTERNS > Instances > Virtual System Instances (Classic).
2. Select the virtual system instance for which you want to restore by using its
snapshot image.
3. Click the Restore icon to restore the virtual system instance to its previously
captured state. The restore process does not take place instantly, and the virtual
system instance is not usable while the virtual system instance is being
restored. After the virtual system instance is restored, it is automatically
stopped and must be restarted manually.
Results
The states of the virtual machines that were part of the virtual system instance are
restored to the same state as when the snapshot image was created. Virtual
machines that were added after the snapshot image was taken are still present and
are unaffected by this process.
What to do next
You can now access the virtual system instance you restored by using the snapshot
image.
Deleting snapshot images:
You can delete a snapshot image of a virtual system instance (classic) that you no
longer require.
Before you begin
You must be granted access to the virtual system instance or have the admin role
to complete this task.
About this task
After creating a snapshot image for a virtual system instance, you can delete the
snapshot when you no longer need it. An existing snapshot image of a virtual
system instance is automatically deleted when a new snapshot image is created.
Procedure
1. Click PATTERNS > Instances > Virtual System Instances (Classic).
2. Select the virtual system instance for which you want to delete the snapshot
image.
3. Click Delete next to the snapshot.
Chapter 7. Managing and deploying virtual patterns

483

Results
The snapshot image is deleted from the system memory.
Virtual System Instances (classic) fields on the user interface:
You can view and work with the virtual system instances in the Virtual System
Instances (classic) window.
Virtual System Instances (classic) fields
The following fields are displayed in a virtual system instance:
Created on
Specifies the date and time when the virtual system instance was created.
This field is automatically generated.
From pattern
Specifies the pattern that was used to create this virtual system instance.
This field is displayed as a link to the associated pattern.
Using Environment profile
Specifies the environment profile, if one was used when creating this
virtual machine, by providing a link to that environment profile. Clicking
the link displays the details for that environment profile. If none was
specified, then this field says None provided.
Current status
Specifies the state of the virtual machine.
Updated on
Specifies the last date and time when the virtual system instance was
updated.
Access granted to
The user who first deployed the virtual system instance is automatically
granted all access to the virtual image as the owner. If you want additional
users to access this virtual system instance, you must manually add the
projects to which these users belong. See User roles in IBM Cloud
Orchestrator on page 255 for more information about object level
permissions.
Snapshot
Includes links to any snapshot images that have been taken of this virtual
system instance.
History
Specifies the activity that has been performed on this virtual system
instance.
Virtual Machines
Lists the virtual machines that are included in this virtual system instance.
If an environment profile was used, then the virtual machine name is
provided by the user who provides the environment profile. Expand any
virtual machine to display detailed information about that virtual machine.
For more information about the virtual machine fields, see Virtual
machine panel fields on the Virtual System Instances (Classic) window on
page 488.

484

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Comments
Specifies optional information a user can append to a virtual system
instance.
Accessing virtual machines in your virtual system instance (classic):
Each virtual system instance consists of a set of virtual machines that represent a
physical node in an application server environment. You can access the individual
virtual machines that make up your virtual system instance from the user interface.
Before you begin
You must specifically be granted access to the virtual system instance you intend
to access. Optionally, you can be assigned the admin role to perform these steps.
About this task
With IBM Cloud Orchestrator, you can access any of the virtual machines that are
contained by the virtual system instances.
Procedure
1. You can access virtual machines from the Virtual System Instances (Classic)
window by clicking PATTERNS > Instances > Virtual System Instances
(Classic) on the menu.
2. From the left panel of the Virtual System Instances (Classic) window, select the
virtual system instance containing the virtual machine. Information about the
virtual system instance is displayed in the right panel of the window.
3. From the right panel of the window, expand Virtual Machines by clicking the
expand icon to view a list of the virtual machines that exists in the selected
virtual system instance.
4. Expand the details for your virtual machine by clicking the expand icon next to
the <virtual_machine_name> for the virtual machine you want to access. The
number of virtual machines that exist for the virtual system instance is
dependent on the pattern that was deployed to create it. From the list of the
virtual machines included in this virtual system instance, you can view the
CPU and the Memory currently being used by a virtual machine.
5. Access your virtual machine. Use one of the following procedure to access your
virtual machine:
v Click Login under the SSH column to open a new browser window and
access the virtual machine using SSH. A prompt is displayed to enter user
name and password.
v Click VNC under the Consoles section to access your virtual machine using
Virtual Network Computing (VNC). During pattern creation, the default
setting is for your host operating system to be configured to accept VNC
connections. VNC connections can be disabled by modifying the virtual
machine properties during pattern creation.
v Click WebSphere under the Consoles section to access the WebSphere
Application Server administrative console on your virtual machine.
Important: To access your virtual machine using VNC or to access
theWebSphere Application Server administrative console on your virtual
machine, your virtual machine must be accessible from the machine you are
accessing the user interface. If a firewall is preventing the connection on the
required port, you must open this port to establish a connection. In addition to
Chapter 7. Managing and deploying virtual patterns

485

this, the DNS server must be correctly configured to resolve the virtual machine
host name. If the DNS is not configured correctly, the ip-address and hostname
fields must be present in the hosts file (/etc/hosts on Linux, and
c:\WINDOWS\system32\drivers\etc\hosts for Windows.
Results
After completing these steps, you have accessed your virtual machine from the
Virtual System Instances (Classic) window of the user interface.
Expanding disk on deployed virtual machines:
Use the Default LINUX resize disk or Default WINDOWS resize disk script
package to expand the disk of a deployed virtual machine.
About this task
After deploying a virtual machine, you can change the related flavor by editing the
Flavor field in the Virtual machines section in the Virtual System Instances
(Classic) window. When you change the flavor only the vCPU and the memory
values are changed. To change the disk size of a deployed virtual machine, you
must follow one of the following procedures:
v If you added the Default LINUX resize disk or Default WINDOWS resize disk
script package to the virtual system pattern before deploying it, perform the
following steps:
1. Click PATTERNS > Instances > Virtual System Instances (Classic) to access
the Virtual System Instances (Classic) window.
2. Select your instance and expand the Virtual Machines detailed section.
3. In the Script Packages section, select theDefault LINUX resize disk or
Default WINDOWS resize disk script package and click Execute now.
For information about adding a script package to a virtual system pattern, see
Associating a script package with a pattern on page 371.
v If the Default LINUX resize disk or Default WINDOWS resize disk script
package is not part of the virtual system pattern, you must download the script
package and run it manually by performing the following steps:
1. Click PATTERNS > Pattern Design > Script Packages to open the Script
Packages window.
2. Select the Default LINUX resize disk or Default WINDOWS resize disk script
package and click Download in the Script package file field in the right
pane.
3. When the file download is completed, upload the
defaultlinuxresizedisk.zip or defaultwindowsresizedisk.zip script
package zip file to the virtual machine where you want to change the disk
size.
4. Unzip the script package file and run the resize script.

486

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Viewing the details for your virtual machines:

Each virtual system instance (classic) consists of a set of virtual machines that
represent a physical node in an application server environment. These virtual
machines are assigned to and hosted by a hypervisor. You can monitor the details
of each of these virtual machines.
Before you begin
You must specifically be granted access to the virtual system instance you intend
to access. Optionally, you can be assigned the admin role to perform these steps.
If the virtual machines are running on a VMware hypervisor, the VMware tools
must be installed in the operating system.
About this task
You can view and monitor the details about each virtual machine in your virtual
system instance by following these steps.
The values are updated frequently and the user interface must be refreshed to get
the newest data.
Procedure
1. From the left panel of the Virtual System Instances (Classic) window, select the
associated virtual system instance in the left panel. Information about the
virtual system instance is displayed in the right panel of the window.
2. From the right panel of the window, expand Virtual Machines by clicking the
expand icon to view a list of the virtual machines that exists on the selected
virtual system instance. The number of virtual machines that exist for a virtual
system instance is dependent on the pattern that was deployed. Some
information is displayed for each virtual machine without having to expand to
see additional details. From the list of virtual machines included in this virtual
system instance, you can view the following details for each virtual machine.
CPU

This field graphically specifies the percentage of the virtual CPU power
that is currently being used. The number of virtual CPUs available is
determined by the pattern used to create the virtual system. The default
number of virtual CPUs for a virtual machine is one.

Memory
This field displays a graph that specifies the percentage of the memory
that is currently being used by the virtual machine. The amount of
memory available is determined by the pattern used to create the
virtual system instance. The default amount of virtual memory for a
virtual machine is 2048 MB.
SSH

This field provides the Login link that you can click to log in to your
virtual machine using Secure Shell (SSH). You are prompted to log on
as a user of your choosing.

Actions
This field displays the available actions for a virtual machine. Actions
that are not available for a specific virtual machine are not active. Click
the View link to show or hide the available actions for the virtual
machine.
Clone Deploys a new instance of the virtual machine with the same
Chapter 7. Managing and deploying virtual patterns

487

parameters. Script packages marked to run at virtual system

creation run after the virtual machine is created. Any
maintenance applied to the source virtual machine is applied to
the cloned virtual machine automatically. The new virtual
machine does not inherit any disk changes made to the source
virtual machine. This action is available if you are viewing a
virtual machine that has completed deployment and is ready to
be cloned.
Note: The tooltip This resource is not ready to be cloned is
shown for images that cannot be cloned temporary or
permanently. It actually means This resource cannot be
cloned.
Start

Restarts a virtual machine that has been stopped.

Stop

Stops a virtual machine that has been started.

Delete Deletes a virtual machine after it is stopped. Resources

associated with the virtual machine are released.
3. Expand the details for a virtual machine by clicking the expand icon next to the
<virtual_machine_name>.
4. View your virtual machine details. For information about the fields shown for
each virtual machine, see Virtual machine panel fields on the Virtual System
Instances (Classic) window.
Virtual machine panel fields on the Virtual System Instances (Classic) window:
You can view information about the virtual machines that are associated with a
virtual system instance using the Virtual machines panel on the Virtual System
Instances (Classic) window of the user interface.
Virtual machine summary fields
The Virtual machines section, before being expanded, shows a status line. The
status line shows the total number of virtual machines, and the number of virtual
machines in each state. For example, the status bar could read: 4 total - 1 deleted 3 started - 1 failed to indicate the total number of virtual machines and how many
are in which state. When expanded, the Virtual machines section lists the
managed virtual machines that IBM Cloud Orchestrator started for the workload.
When the Virtual machines section is expanded, the following fields are provided
for each virtual machine listing, without expanding the details for each virtual
machine:
Name The name of the virtual machine that is included in the virtual system
being viewed. If an environment profile was used, then the virtual
machine name could have been provided by the user who provided the
environment profile.
CPU

Provides the graphic and numeric percentage of available CPU being used
by this virtual machine.

Memory
Provides the graphic and numeric percentage of available memory being
used by this virtual machine.
SSH

488

Clicking the Login link opens a dialog to log in to an SSH session.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Actions
Clicking the View link displays or hides the following set of icons to work
with this virtual machine:
Clone Deploys a new instance of the virtual machine with the same
parameters. Script packages marked to run at virtual system
creation run after the virtual machine is created. Any maintenance
applied to the source virtual machine is applied to the cloned
virtual machine automatically. The new virtual machine does not
inherit any disk changes made to the source virtual machine. This
action is available if you are viewing a virtual machine that has
completed deployment and is ready to be cloned.
Note: The tooltip This resource is not ready to be cloned is
shown for images that cannot be cloned temporary or permanently.
It actually means This resource cannot be cloned.
Start

Restarts a virtual machine that has been stopped.

Stop

Stops a virtual machine that has been started.

Delete Deletes a virtual machine after it is stopped. Resources associated

with the virtual machine are released.
Check box
Checking the check box in the header of this column selects all of the
virtual machines that have not been deleted. Clearing the check box in the
header row also clears all of the virtual machines in the listing. Use this
check box with the Group Actions link to apply an action to the selected
group of virtual machines.
Group Actions
Select this check box to apply an action to the group of virtual machines
selected. Actions can be applied to all of the virtual machines that have not
been deleted or to a selected group of virtual machines.
General information
When the view of any individual virtual machine is expanded, the General
information section shows the following information about that virtual machine:
Created on
Specifies the time and the date the virtual machine was created. This field
is automatically generated for managed virtual machines.
From virtual image
Specifies the virtual image that was used when creating this virtual
machine by providing a link to that virtual image in the catalog. Clicking
the link displays the details for that virtual image.
Note: After applying a service pack, the templateid of the virtual machine
might be updated. For example, this templateid might be updated from
70017 to 70019. This is an expected behavior.
Part name
The name of the part. This field is not available for unmanaged virtual
machines.
Current status
Specifies the status of the virtual machine.

Chapter 7. Managing and deploying virtual patterns

489

Updated on
Specifies the time and date of the last change to the virtual machine.
On hypervisor
Specifies the hypervisor where this virtual machine is located by providing
a link to the hypervisor details panel. You can click the link to display the
details of the hypervisor where this virtual machine is running.
In cloud group
Specifies the cloud group where this virtual machine is located by
providing a link to the Cloud Groups panel. You can click the link to
display the details of the cloud group where this virtual machine is
running.
Registered as
Specifies how the virtual machine is registered on the hypervisor.
Stored on
Specifies the storage device associated with this virtual machine.
Hardware and network
The Hardware and network section provides the following fields:
Flavor Specifies the instance flavor that describes the memory and storage
capacity of the virtual machine. By default the flavor values are:
m1.tiny
Memory: 512 MB, vCPUs: 1, Storage: 0 GB
m1.small
Memory: 2048 MB, vCPUs: 1, Storage: 20 GB
m1.medium
Memory: 4096 MB, vCPUs: 2, Storage: 40 GB
m1.large
Memory: 8192 MB, vCPUs: 4, Storage: 80 GB
m1.xlarge
Memory: 16384 MB, vCPUs: 8, Storage: 160 GB
To change the flavor, stop the virtual machine and click Edit to select a
new flavor value. When you confirm your change, the virtual machine is
automatically restarted.
Note: When you change the flavor only the vCPU and the memory values
are changed. To change the disk size of a deployed virtual machine, you
must follow the procedure described in Expanding disk on deployed
virtual machines on page 486.
Note: If you are using IBM Cloud Orchestrator in languages other than
English, the Flavor field might be displayed as Untranslated message
RM11388.
Virtual CPU count
Specifies the number of CPU this virtual machine represents. This value is
specified in the pattern that was deployed to create the virtual system
instance. See Working with virtual system patterns (classic) on page 434
for more details on the pattern options.

490

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Physical CPU
Specifies whether the physical CPUs are reserved for exclusive use by this
virtual machine. The Reserved status is shown if the True value is selected
for Reserve physical CPUs during deployment and it is an image variable.
CPU shares on host
The amount of CPU allocated for the host.
CPU shares consumed on host
The amount of CPU actually used by the host.
Virtual memory (MB)
Specifies the IP address and the host name of this virtual machine. The
virtual machine must be stopped before this value can be changed.
SSH public key
The name of, and a link to, the public key.
Network interface
The network interface address.
MAC address
Specifies the Media Access Control (MAC) address of the virtual machine.
Operating System
The Operating System section provides the following fields:
Name Specifies the type of operating system that is running on the virtual
machine.
Type

Shows the specific variety of the operating system that is running on the
virtual machine.

Version
Specifies the equivalent of the uname - a command for the operating
system on the virtual machine.
Note: After applying a service pack, the version of the operating system
might not be displayed by the uname - a command. The initial value is
obtained from the virtual machine, which is then stored in the database.
This is expected behavior.
WebSphere Configuration
The WebSphere Configuration section provides the following fields:
Cell Name
The cell in which this virtual machine resides.
Node Name
The node in which this virtual machine resides.
Profile Name
The profile in which this virtual machine was run.
Show all environment variables
This link specifies the set of supplied environment variables that you can
use when using a script package. See Script package environment
variables on page 388 for more information about the environment
variables.

Chapter 7. Managing and deploying virtual patterns

491

Script Packages
The Script Packages section lists any script packages that have been run on this
virtual machine. If any script packages have been run for this virtual machine, then
links to the associated log files are also included. See Managing script packages
on page 365 for more information about script packages.
If a script is user initiated, meaning the executes attribute is set as when I initiate it,
then the start icon is displayed next to the script name. Click the icon to run the
script. There is no limit on the number of times a script is run using this method.
Scripts in this section can include add-ons. For more information about add-on
scripts, see Managing add-ons on page 408.
Consoles
The Consoles section provides a link to access your virtual machine. Using the
provided links, you can access the WebSphere Application Server administrative
console for your virtual machine. See Accessing virtual machines in your virtual
system instance (classic) on page 485 for more information about accessing you
virtual machines.

Managing pattern types

A virtual application pattern type is a collection of plug-ins that identify components,
links and policies, along with configuration files, packaged in a .tgz file. The
virtual application patterns are used to build a virtual application that includes
these components, links and policies.

About this task

The following pattern type is shipped with IBM Cloud Orchestrator:
v IBM Foundation Pattern. It provides shared services for deployed virtual
applications such as monitoring and load balancing.
Note: The Foundation Pattern is a prerequisite to using all other pattern types.
Note: Not all patterns might work for all Hypervisors.
Other pattern types are purchasable at the IBM PureSystems Centre.
The virtual system pattern has been tested successfully on the following operating
systems:
v SUSE Linux Enterprise Server 11 SP1, SP2, or SP3, 32-bit or 64-bit.
v Red Hat Enterprise Linux 5.x, Red Hat Enterprise Linux 6.1, 6.2, 6.3, 6.4, 6.5, or
6.6 32-bit or 64-bit.
v CentOS 6.3 or 6.4, 64-bit Windows 2008 R2 64-bit,
v Windows 7 64-bit, Windows Server 2012 64-bit, Windows 8 64-bit.
Note: The following pattern types are supported by the current version of IBM
Cloud Orchestrator:
foundation
2.1.0.0
dbaas
1.1.2.0
webApp 1.0
1.0.1.0
webApp 2.0
2.0.2.0
application 1.0.2.0

492

IBM Cloud Orchestrator 2.4.0.2: User's Guide

If you created virtual applications that contain these pattern types, ensure to
download the supported version of the pattern types to continue to use your
virtual applications in IBM Cloud Orchestrator.
Use the following steps to work with pattern types:

Procedure
1.
2.
3.
4.

View the pattern types.

View the system plug-ins in the pattern types.
Import a pattern type.
Accept the pattern license agreement. You must accept the license agreement
for each pattern type that you want to use. You can accept the license by
following these steps:
a. Click PATTERNS > Pattern Types. The Pattern Types palette displays and
the pattern types are listed.
b. Select a pattern_type. The pattern details display on the right.
c. In the License Agreement field, click Accept. The dialogue window
displays for the pattern type.
d. After reading the license agreement, click Accept. The license agreement
details changes to Accepted.
e. Click Enable to change the pattern type status to Available.
Important: By default, there is not a license agreement to accept for the
Foundation Pattern type. But, the Foundation Pattern must be made
available before the other pattern types can be made available and used.

For detailed information about accepting the license agreement for specific
pattern types, see the related pattern type documentation.
5. Upgrade a pattern type.
6. Remove a pattern type.

Results
You are ready to start creating or extending virtual applications with pattern types.

Viewing pattern types

The system includes a set of pattern types that you can use to create
solution-specific virtual applications.

Before you begin

The IBM Foundation Pattern type is shipped with IBM Cloud Orchestrator. Other
pattern types are purchasable at the IBM PureSystems Centre.
By default, there is not a license agreement to accept for the foundation pattern
type. However, the foundation pattern type must be enabled before the other
pattern types can be enabled. The foundation pattern type is a prerequisite to
using all other pattern types.

About this task

You can view information about the pattern type in the user interface by following
these steps:
Chapter 7. Managing and deploying virtual patterns

493

Procedure
1. Click PATTERNS > Deployer Configuration > Pattern Types. The Pattern
Types palette displays and the pattern types are listed.
2. Select a pattern_type. The pattern details display on the right.
3. View the details of the pattern type, including:
Description
Specifies the description of the pattern type.
License agreement
Specifies if the license agreement is accepted.
Status Specifies the status of the pattern type: Disabled or Available. To
enable the pattern type, select Enable. After you enable the pattern
type, the status is changed to Available. You can either enable the
current pattern type of no dependencies exist, or enable all of the
pre-requirements, such as accepting licenses and updating statuses.
Required
Specifies any prerequisite patterns that are required.
Plug-ins
Specifies the plug-ins that are associated with this pattern type. Click
show me all plug-ins in this pattern type to view plug-ins associated
with the pattern type. Plug-ins required for configuration are also
listed.
Dependency
Lists pattern type dependencies.

Viewing the plug-ins in the pattern types

You can view the system plug-ins that are associated with the pattern types.

Procedure
1. Click PATTERNS > Deployer Configuration > Pattern Types. The Pattern
Types palette displays and the pattern types are listed.
2. Select a pattern_type. The pattern details display on the right.
3. Click show me all plug-ins in this pattern type and the System Plug-ins
palette displays with a list of plug-ins.

Results
You have viewed the plug-ins that are associated with the pattern type.

Importing pattern types

You can import a new pattern type to IBM Cloud Orchestrator.

Before you begin

You must be assigned the admin role to perform these steps.
Note: To upload a file that is larger than 2 GB, you must upload it from a remote
system. To upload a file from a local system, the size of the file must be smaller
than 2 GB.

494

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

Complete the following procedure to upload and import a new pattern type from a
local system.
Restriction: It is not possible to import multiple pattern types simultaneously.
Multiple pattern types must be imported one at a time: the next import can start
only if the previous imported pattern is visible in the list of available pattern types.

Procedure
1. Click PATTERNS > Deployer Configuration > Pattern Types. The Pattern
Types palette is displayed.
2. Click the New icon. The Install a pattern type window is displayed.
3. Select the Local tab, and click Browse to select the .tgz file to import as a
pattern type. Your system proceeds to upload the .tgz file.

Results
You have imported a new pattern type.

What to do next
Now you must accept the license agreement of the pattern type, configure plug-ins
in this pattern type, and enable the pattern type if you want to use it.

Removing a pattern type

You can remove a pattern type from the IBM Cloud Orchestrator.

Before you begin

You might not be able to delete a pattern type if one or more of the following is
true:
v The pattern type is in use, for example, the pattern type is associated with
deployed a application.
v The pattern type is a prerequisite of another pattern type, such as the IBM
Foundation Pattern.
v One or more plug-ins of this pattern type is in use, for example, the plug-ins are
associated with a deployed application.

About this task

Procedure
1. Click PATTERNS > Deployer Configuration > Pattern Types. The Pattern
Types palette displays.
2. Select the pattern type to delete.
3. Click the Delete this pattern type icon. The Do you really want to delete this
pattern type window displays.
4. Click OK to delete the pattern type.

Results
You have removed a pattern type.

Chapter 7. Managing and deploying virtual patterns

495

Upgrading pattern types

Periodic updates are available for pattern types.

Before you begin

The pattern type updates are available at IBM Fix Central.

About this task

Pattern types are packaged in a .tgz file, whether the delivery is in release, update
or fix pack. For example, a web application pattern update looks like the
following: webapp-x.x.x.x.tgz (release), webapp-x.x.x.x.tgz (update on Fix Central)
or webapp-x.x.x.x.tgz (update through a fix pack on Fix Central), where x.x.x.x is
the release level.
If you download an update from Fix Central, and import the file into IBM Cloud
Orchestrator, the administrator must accept the license agreement and make the
version.release (VR) available. If you download a fix pack that includes updated
pattern type and import the file into IBM Cloud Orchestrator, the new pattern type
license is already accepted and the pattern type is automatically available to the
user.
The following guide explains how various users are impacted by pattern type
updates:
v The user is exposed to pattern types at VR when they create a workload.
v The administrator can import and delete pattern types at
version.release.minor.fixpack (VRMF).
v The administrator manages plug-ins in pattern types at VR. The administrator
does not need to know which VRMF contains the latest of plug-ins that are used
in the VR.
v New workloads are based on the latest plug-ins within that VR; locked
applications and existing deployments are not affected.
v For an update, the administrator must accept the license agreement and make
the VR available.
v Users see a new pattern type when creating a workload (pattern type at VR).
After you download the fixes from Fix Central, you can import the new pattern
type by performing the following steps:

Procedure
1. Click PATTERNS > Deployer Configuration > Pattern Types. The Pattern
Types palette displays.
2. Click the New icon. The Install a new pattern type window displays.
3. Click Browse to select the .tgz file to import as a pattern type. Your system
proceeds to upload the .tgz file.

Results
You have imported an updated .tgz file as an upgraded pattern type.

496

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Upgrading a deployed pattern type

You can upgrade a pattern type that is associated with a virtual application
instance through the IBM Cloud Orchestrator user interface.

Before you begin

The pattern type license must be enabled before you can upgrade. Click
PATTERNS > Deployer Configuration > Pattern Types > pattern_type > Enable.

About this task

Perform the following steps:

Procedure
1. View the virtual application instances. Click PATTERNS > Instances > Virtual
Application Instances.
2. Select the virtual_application_instance for which you want to upgrade the
pattern type. Click the Upgrade icon. A dialogue box displays where you can
confirm that you want to upgrade the pattern type to the latest version. Click
OK. A message displays across the menu that the pattern type is upgrading.
When the upgrade is complete, the Status field arrow turns green.

Pattern type packaging reference

The pattern types are a collection of plug-ins. The plug-ins contain the
components, policies and links of the virtual application pattern. This topic
explains the packaging of the plug-ins that create the virtual application pattern
type.
Virtual application pattern types are shipped with IBM Cloud Orchestrator or they
are purchasable at the IBM PureSystems Centre.
The associated plug-in files that are associated with a pattern type are as follows:
v {ptype}.tgz file
v plugins/set of {plugin}.tgz files
v files/set of {name} files
The {ptype}.tgz file is required and must contain the patterntype.json file. The
{ptype}.tgz file might also contain the license and localized messages. For
example, the patterntype.json file for the IBM Web Application Pattern (not
released with the product) is as follows:
{
"name":"NAME",
"shortname":"webapp",
"version":"2.0.0.0",
"description":"DESCRIPTION",
"prereqs":{
"foundation":"*"
},
"license":{
"pid":"5725D57",
"type":"PVU"
}
}

A pattern type defines a logical collection of plug-ins, but not the members. The
members (plug-ins) define their associations with pattern types in the config.json
Chapter 7. Managing and deploying virtual patterns

497

file. Therefore, pattern types are dynamic collections and can be extended by third
parties. For example, the config.json file for the DB2 plug-in (not released with
the product) is as follows:
{
"name":"db2",
"version":"2.0.0.0",
"files":[
"db2/db2_wse_en-9.7.0.3a-linuxx64-20110330.tgz",
"optim/dsadm223_iwd_20110420_1600_win.zip",
"optim/dsdev221_iwd_20110421_1200_win.zip",
"optim/com.ibm.optim.database.administrator.pek_2.2.jar",
"optim/com.ibm.optim.development.studio.pek_2.2.jar"
],
"patterntypes":{
"primary":{
"dbaas":"1.0"
},
"secondary":[
{
"webapp":"2.0"
}
]
},
"packages":{
"DB2":[
{
"persistent":true,
"requires":{
"arch":"x86_64"
},
"parts":[
{
"part":"parts/db2-9.7.0.3.tgz",
"parms":{
"installDir":"/opt/ibm/db2/V9.7"
}
},
{
"part":"parts/db2.scripts.tgz"
}
]
}
]
}
}

Working with virtual applications

IBM Cloud Orchestrator provides support for creating application-centric
deployments called virtual applications. Virtual application builders and deployers
describe virtual applications in terms of the application artifacts and required
quality of service levels. IBM Cloud Orchestrator determines the infrastructure and
middleware that is required to host the virtual application at deployment time.

Virtual application patterns

IBM Cloud Orchestrator provides a generic framework for designing, deploying,
and managing virtual applications. The model that you build by using the
application artifacts and quality of service levels is called a virtual application
pattern. You can use predefined patterns, extend existing patterns, or create new
ones.

498

IBM Cloud Orchestrator 2.4.0.2: User's Guide

When you build a virtual application pattern, you create the model of a virtual
application by using components, links, and policies.
Consider an order management application with the following requirements:
v It is web-based and runs on WebSphere Application Server.
v It is highly available, with a cluster of two WebSphere Application Server nodes
and two DB2 nodes.
v It uses DB2 to store order information and other application data.
v It supports the current maximum number of orders that are received by the
company, 10 transactions per second, but it must also be able to scale to handle
a larger number of transactions, up to 15 transactions per second, as the business
increases.
v It supports backup and restore capabilities.
A virtual application builder can use IBM Cloud Orchestrator to create a virtual
application pattern by using components, links, and policies to specify each of
these parameters.
Component
Represents an application artifact such as a WAR file, and attributes such
as a maximum transaction timeout. In terms of the order management
application example, the components for the application are the WebSphere
Application Server nodes and the DB2 nodes. The WebSphere Application
Server components include the WAR file for the application, and the DB2
components connect the application to the existing DB2 server.
Link

A connection between two components. For example, if a web application

component has a dependency on a database component, an outgoing link
from the web application component to the database component defines
this dependency. In terms of the order management application example,
links exist between the WebSphere Application Server components and the
DB2 components.

Policy Represents a quality of service level for application artifacts in the virtual
application. Policies can be applied globally at the application level or
specified for individual components. For example, a logging policy defines
logging settings and a scaling policy defines criteria for dynamically
adding or removing resources from the virtual application. In terms of the
order management application example, a Response Time Based scaling
policy is applied that scales the virtual application in or out to keep the
web response time 1000 - 5000 ms.
When you deploy a virtual application, the virtual application pattern is converted
from a logical model to a topology of virtual machines that are deployed to the
cloud. Behind the scenes, the system determines the underlying infrastructure and
middleware that is required for the application, and adjusts them as needed to
ensure that the quality of service levels that are set for the application are
maintained. A deployed topology that is based on a virtual application pattern is
called a virtual application instance. You can deploy multiple virtual application
instances from a single virtual application pattern.
The components, links, and policies that are available to design a particular virtual
application pattern are dependent on the pattern type that you choose and the
plug-ins that are associated with the pattern type.

Chapter 7. Managing and deploying virtual patterns

499

Virtual application pattern types and plug-ins

A pattern type represents a collection of related components, links, and policies that
are used to build a set of virtual applications. A pattern type defines a virtual
application domain. For example, the IBM Web Application Pattern pattern type
(not released with the product) defines a domain in which J2EE web applications
are deployed. It includes components for WAR, EAR, and OSGiEBA files. These
components have an attribute for the appropriate archive file, which an application
builder specifies during construction of the virtual application pattern.
The web application can connect to a database, so the pattern type also includes a
component to represent the database and provides its connection properties as
attributes. The pattern type also defines a link between the database and the WAR
file to represent communication between the application and the database.
The application components (WAR, EAR, OSGiEBA) can all be configured with
quality of service levels by applying policies. The available options include scaling,
routing, logging, and JVM policies.
The plug-ins that are associated with Web Application Pattern define these
components, links, and policies. They also provide the underlying implementation
to deploy the virtual applications in the cloud and perform maintenance on
deployed virtual application instances.
Virtual application builders create virtual application patterns in the Pattern
Builder. Within Pattern Builder, you begin by selecting the pattern type that you
want to use. This choice determines the set of components, links, and policies that
you can use to build the virtual application and the type of virtual applications
that you can create.
Plug-in developers are responsible for creating or customizing pattern types and
plug-ins that control the available components, links, and policies and
corresponding configuration options, as well as the code for implementing
deployments.

Options for reusing virtual application configuration

To simplify complex application design and standardize reuse of common
components and configuration across multiple virtual applications, you can
leverage several options:
virtual application templates
A predefined virtual application pattern that can include components that
are already pre-configured. You can use a template as a foundation for
creating virtual application patterns that use the same basic configuration.
Alternatively, you can deploy a virtual application directly from a template
and specify any required settings at deployment time.
virtual application layers
A grouping of components within a virtual application pattern. You can set
up multiple layers within a single virtual application pattern or you can
import one virtual application pattern into another as a reference layer.
Reusable components
You can pre-configure a virtual application component and save it for
reuse by any virtual application pattern based on the same pattern type.

500

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Creating a virtual application pattern

Complete the following steps to get started with creating a virtual application
pattern.
1. Design your application. You can create a new virtual application pattern, or
create one based on an existing template.
v Create a virtual application pattern
Virtual application patterns are fully configured before you deploy them.
v Create a virtual application template
Virtual application templates are designed for more flexibility. Properties can
be left unconfigured or configured with default values and users who deploy
virtual applications can specify the required values at deployment time.
2. Link components and configure them.
3. Groups components into layers or import a virtual application into your virtual
application pattern as a layer.

Virtual application pattern components

A virtual application pattern contains components that represent middleware
services that are required by the virtual appliance instance.
You can connect components in a virtual application pattern to indicate
dependencies and optionally apply a policy to configure middleware services
during deployment to configure specific behavior or define a quality of service
level. Components, links, and policies can have required and optional attributes.
Components, links, and policies are defined by plug-ins. When you create a virtual
application pattern, the available components, links, policies, and configuration
options are determined by the plug-ins that are included with the selected pattern
type.
Note: Not all patterns might work for all Hypervisors.
The virtual application pattern was tested successfully on the following operating
systems:
v WebSphere Application Server 8.5.5.1.
v WebSphere Application Server 8.5.0.2.
v DB2 10.5.

Components
The following components are available with the virtual application patterns
provided with IBM Cloud Orchestrator or purchasable at the IBM PureSystems
Centre.
Important: Components that require disk add-ons are not supported in IBM Cloud
Orchestrator.
v Application
Additional archive file
Enterprise application
Existing web service provider endpoint on page 525
Policy set on page 526
Chapter 7. Managing and deploying virtual patterns

501

 Web application, such as IBM WebSphere Application Server

v Database
Data Studio web console
Database, such as IBM DB2
Existing database (DB2) on page 536
Existing database (Informix)
Existing database (Oracle)
Existing IMS database on page 541
v Messaging
Existing Messaging Service (WebSphere MQ) on page 553
Existing queue (WebSphere MQ) on page 556
Existing topic (WebSphere MQ) on page 555
v OSGi
External OSGi bundle repository
OSGi application
v Transaction Processing
CICS Transaction Gateway.
Existing IMS TM on page 565.
v User Registry
Existing User Registry (IBM Tivoli Directory Server) on page 542
Existing User Registry (Microsoft Active Directory) on page 546
User Registry (Tivoli Directory Server) on page 549
v Other components
Generic target
Debug on page 609

Policies
You can optionally apply policies to a virtual application to configure specific
behavior in the deployed virtual application instance. Two virtual applications
might include identical components, but require different policies to achieve
different service level agreements. For example, if you want a web application to
be highly available, you can add a scaling policy to the web application component
and specify requirements such as a processor usage threshold to trigger scaling of
the web application. At deployment time, the topology of the virtual application is
configured to dynamically scale the web application. Multiple WebSphere
Application Server instances are deployed initially for the web application and
instances are added and removed automatically based on the service levels that are
defined in the policy.
Policies can be applied only to particular types of components. For more
information, see the following links:
v Scaling policy
v Routing policy
v Java virtual machine (JVM) policy
v Log policy

502

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Managing virtual applications

A virtual application is defined by a virtual application pattern. It is a complete set
of platform resources that fulfill a business need, including web applications,
databases, user registries, messaging services and transaction processes. The
pattern used to create the virtual application is a collection of plug-ins that provide
these resources and services in the form of components, links and policies.

Before you begin

To manage virtual applications, you must have the catalogeditor role or the admin
role. You must also accept the license agreements for the pattern types in your
environment before you can use the pattern type to create and extend virtual
applications.
Note: The base image for virtual applications must be downloaded from Passport
Advantage. Its name is IBM OS Image for Red Hat Linux Systems. We recommend
always to get the latest available version.

About this task

The plug-in component, links and policies are selected when you create or extend
your virtual application in the Pattern Builder. You can find information about
plug-in components, links, and policies at Virtual application pattern
components on page 501. You can start with a virtual application template of an
application. The virtual application is deployed to the cloud and becomes a virtual
application instance.

Creating virtual application patterns

Create virtual application patterns to model virtual applications that you can
deploy to the cloud.

Before you begin

You must be assigned the catalogeditor role or the admin role.
Note: The base image for virtual applications must be downloaded from Passport
Advantage. Its name is IBM OS Image for Red Hat Linux Systems. We recommend
always to get the latest available version.

About this task

When you create a virtual application, you first select a pattern type. The pattern
type abstracts the infrastructure and middleware layers for a particular type of
workload, such as a web application. You can then create a virtual application
pattern by using the components associated with the selected pattern type.
Use the Pattern Builder to define, create, and deploy your virtual applications. For
example, rather than installing, configuring, and creating a connection to a specific
instance of a database, you can specify the need for a database and provide the
associated database schema in your virtual application pattern. The database
instance and the connection in the cloud is then created for you by the workload
pattern.

Chapter 7. Managing and deploying virtual patterns

503

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The Virtual
Application Patterns palette displays.
2. Click the Add icon on the toolbar.
3. To build your virtual application pattern:
a. Select a pattern type from the drop-down menu.
b. Select a virtual application template.
c. Click Start Building. You have created a new virtual application associated
with a pattern type. The Pattern Builder opens in a new window where you
can add components and policies.
4. On the Virtual Application properties pane, specify the following information:
Name The name of the virtual application pattern.
Description
(Optional) The description of the virtual application pattern.
Type

Leave Application selected to create a virtual application pattern or

select Template to create a virtual application template that is used as
the basis for creating other virtual application patterns.

Lock option for plugin usage

Specify how this virtual application pattern is affected by upgrades to
the pattern type or to IBM Foundation Pattern.
Unlock plugins
If the pattern type is upgraded use the latest versions of pattern
type plug-ins. If IBM Foundation Pattern is upgraded, use the
latest version.
Lock all plugins
Do not change the version of plug-ins or the version of the IBM
Foundation Pattern associated with this virtual application
pattern when an upgrade occurs.
Lock all plugins except Foundation plugins
If the pattern type is upgraded, do not change the version of
the plug-ins associated with this virtual application pattern. If
IBM Foundation Pattern is upgraded, use the latest version.
Note: You can view a list of which plug-ins are locked if you select
Lock all plugins or Lock all plugins except Foundation plugins. Click
the Source tab in Pattern Builder. The application model source is
displayed. Search for the element plugins to view the list.
5. If you selected a blank template, the canvas is empty and you can start
building the virtual application. If you selected a template, customize the
virtual application:
v Drag the components that you want to add to the virtual application pattern
onto the canvas.
v To add policies to the virtual application pattern, click Add policy for
application and select a policy or select a component part on the canvas and
click the Add a Component Policy icon to add a component-specific policy.
v To remove parts, click the Remove Component icon in the component part.

504

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v To edit the connections between the parts, hover over one of the objects until
the blue circle turns orange. Select the circle with the left mouse button, drag
a connection to the second object until the object is highlighted, and release
the mouse button.
6. Click Save.

Results
The virtual application pattern is created.

Editing virtual application patterns

You can edit a virtual application pattern to add or remove application
components, links and policies.

Before you begin

You must be granted access to the pattern or assigned the admin role.

About this task

Use the Pattern Builder to edit your virtual application pattern. You can add, edit
or remove components, links and policies.

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The Virtual
Application Patterns palette displays.
2. Select a virtual application pattern and click the Open icon.
3. Edit the virtual application pattern, as required:
v Drag the components that you want to add to the virtual application pattern
onto the canvas.
v To add policies to the virtual application pattern, click Add policy for
application and select a policy or select a component part on the canvas and
click the Add a Component Policy icon to add a component-specific policy.
v To remove parts, click the Remove Component icon in the component part.
v To edit the connections between the parts, hover over one of the objects until
the blue circle turns orange. Select the circle with the left mouse button, drag
a connection to the second object until the object is highlighted, and release
the mouse button.
4. Click Save.

What to do next
Deploy the virtual application.

Cloning virtual application patterns

Use the console to clone an existing virtual application pattern.

Before you begin

You must be granted access to the pattern and be assigned the catalogeditor role
or the admin role.

Chapter 7. Managing and deploying virtual patterns

505

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual application pattern and click the Clone icon on the toolbar.
3. Specify the name for the copy of the virtual application pattern and click OK.

What to do next
Edit the cloned virtual application pattern as necessary.

Deleting virtual application patterns

You can delete virtual application patterns that you no longer need to deploy.

Before you begin

You must be granted access to the application pattern or assigned the admin role.

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual application pattern. The virtual application pattern details
display in the right pane.
3. Click the Delete icon on the toolbar.
4. Click Confirm to confirm that you want to delete the pattern.

Results
You deleted a virtual application pattern.

Creating virtual application layers

You can use the Pattern Builder in IBM Cloud Orchestrator to create virtual
application layers, which provides a way for you to control the complexity and
reuse virtual applications.

About this task

By default, a virtual application consists of one layer when you first create it.
When you use application layering, you can modify an existing virtual application
by adding separate layers. For example, you can use one virtual application that
defines the basic components of one deployment environment to create a different
virtual application for other deployment environments by associating the quality of
service (QoS) layer with different QoS goals.
One virtual application can contain multiple layers. A layer can contain component
types of the virtual application, or the layer can reference another virtual
application, which is called a reference layer.
Because there is no predefined set of layers or binding between a component type
and a particular layer, you can create layers according to your business goals.
However, one component type in a virtual application can be placed in only one
layer, but you can move parts between the layers.
You use the Pattern Builder do add or delete a layer, edit a layer, disable or enable
a layer, move virtual application parts between layers, or import a virtual
application as a reference layer.

506

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Follow these steps to create an application layer:

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The Virtual
Application Pattern palette displays.
2. Select the virtual application for which you want to create a layer.
3. Click the Open icon to edit the pattern layer. The Pattern Builder displays. The
Layers palette displays on the bottom left of the Pattern Builder. The
topographical view of the virtual application pattern displays on the canvas.
4. Expand Layers to view the layers of the virtual application. Click the layer to
view the topographical view on the canvas.
5. Click the Create a new layer icon. The new layer is added to the Layers
palette.
You can also add a layer by importing an existing application called a reference
layer.
6. Click Save.

Results
You have created a layer for your virtual application.

What to do next
Edit the layer.

Editing virtual application layers

You can use the Pattern Builder in IBM Cloud Orchestrator to edit virtual
application pattern layers.

About this task

By default, a virtual application includes one layer when you first create it. When
you use application layering, you can modify an existing virtual application by
adding separate layers. For example, you can use one virtual application that
defines the basic components of one deployment environment to create a different
virtual application for other deployment environments by associating the quality of
service (QoS) layer with different QoS goals.
One virtual application can contain multiple layers. A layer can contain component
types of the virtual application, or the layer can reference another application,
which is then called a reference layer.
Because there is no predefined set of layers or binding between a component type
and a particular layer, you can create layers according to your business goals.
However, one component type in a virtual application can be placed in only one
layer, but you can move parts between the layers.
In the Pattern Builder, you can add or delete a layer, edit a layer, disable or enable
a layer, move virtual application parts between layers, or import a virtual
application as a reference layer.
To edit a virtual pattern application layer:

Chapter 7. Managing and deploying virtual patterns

507

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The Virtual
Application Pattern palette displays.
2. Select the virtual application pattern for which you want to edit a layer.
3. Click the Edit icon. The Pattern Builder opens.
4. Expand Layers to view the layers of the virtual application pattern. Click the
layer to view the topographical view on the canvas and to start editing.
5. Edit the layer. You can edit the layer in the following ways:
v Rename the layer. Click one time on the name to modify.
v Add or remove virtual application components.
v Add or remove virtual application components connections.
v Add or remove policies.
v Move components between layers. Use the move to: icon to switch the layer
group of each virtual application pattern part. When you select a virtual
application pattern part and click the move to: icon, a list of layers displays.
Select a layer to move the virtual application pattern part from the previous
layer.
6. Click Save.

Results
You have edited an existing virtual application pattern layer.

What to do next
Deploy the virtual application pattern.

Deleting virtual application pattern layers

You can use the Pattern Builder in IBM Cloud Orchestrator to delete virtual
application pattern layers.

About this task

In the Pattern Builder, you can add or delete a layer, edit a layer, disable or enable
a layer, move virtual application parts between layers, or import a virtual
application as a reference layer.

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The Virtual
Application Patterns palette displays.
2. Select the virtual application pattern for which you want to remove a layer.
3. Click the Edit icon. The Pattern Builder opens. The Layers palette displays on
the lower left of the Pattern Builder. The topographical view of the virtual
application pattern displays on the canvas.
4. Expand Layers to view the layers of the virtual application pattern.
5. Select the layer that you want to delete and click the Delete the selected layer
icon. The topographical view displays on the canvas to show that the layer is
deleted.

Results
You deleted a virtual application pattern layer.

508

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Importing virtual application pattern layers

You can use the Pattern Builder in IBM Cloud Orchestrator to import an
application as a reference layer.

About this task

In the Pattern Builder, you can add or delete a layer, edit a layer, disable or enable
a layer, move virtual application patterns parts between layers, or import a virtual
application pattern as a reference layer.
Use reference layers to reuse existing applications. Contents in the reference layer
are read-only. Changes made from the referenced application are reflected in the
application referencing it.
To import a new layer as a reference:

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The Virtual
Application Patterns palette displays.
2. Select the virtual application pattern for which you want to import a layer.
3. Click the Edit icon. The Pattern Builder opens. The Layers palette displays on
the lower left of the Virtual Application Patterns palette. The topographical
view of the virtual application pattern displays on the canvas.
4. Expand Layers to view the layers of the virtual application pattern.
5. Click the Import a virtual application icon. The Import Virtual Application
dialog box displays.
6. Select a virtual application that you want to reference as a layer and click Add.
The new application layer is now listed under the Layers palette. If you select
this layer, the topographical view displays on the canvas.

Results
You have imported a virtual application as a reference layer.

What to do next
After you import the reference layer, virtual application pattern components in
other layers can connect to the reference layer.

Working with virtual application templates

The virtual application template is a predefined set of components and configuration
used to simplify and standardize the creation of virtual application patterns.

Before you begin

You must be assigned the catalogeditor role or the admin role to work with virtual
application templates.

About this task

When you design a virtual application template, you can configure it with default
values or leave some values unconfigured. Application builders can use the virtual
application template to create new virtual application patterns. virtual application
templates also provide a more flexible deployment option. When you deploy from
Chapter 7. Managing and deploying virtual patterns

509

a virtual application template, you can specify property values that are not
configured or edit values that are not locked.
To access the virtual application templates, click PATTERNS > Pattern Design >
Virtual Application Templates.
Creating a virtual application template:
You can create a new virtual application template that is used to create a virtual
application. The template can be saved in the IBM Cloud Orchestrator catalog.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
You can also use an existing virtual application template that was shipped with the
product or you can create a virtual application template from an existing virtual
application.
To create a virtual application template from an existing virtual application, click
PATTERNS > Pattern Design > Virtual Application Patterns and select a virtual
application in the list. Click the New icon to create a virtual application template.
Click the Edit icon to start the Pattern Builder.
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. Click the New icon on the toolbar.
3. To create your virtual application template:
a. Select a pattern type from the drop-down menu.
b. Select a virtual application template.
c. Click Start Building. You have created a new virtual application template
associated with a pattern type. The Pattern Builder opens in a new window
where you can add components and policies.
4. On the Virtual Application properties pane, specify the following information:
Name The name of the virtual application pattern.
Description
(Optional) The description of the virtual application pattern.
Type

Leave Application selected to create a virtual application pattern or

select Template to create a virtual application template that is used as
the basis for creating other virtual application patterns.

Lock option for plugin usage

Specify how this virtual application pattern is affected by upgrades to
the pattern type or to IBM Foundation Pattern.
Unlock plugins
If the pattern type is upgraded use the latest versions of pattern
type plug-ins. If IBM Foundation Pattern is upgraded, use the
latest version.
Lock all plugins
Do not change the version of plug-ins or the version of the IBM

510

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Foundation Pattern associated with this virtual application

pattern when an upgrade occurs.
Lock all plugins except Foundation plugins
If the pattern type is upgraded, do not change the version of
the plug-ins associated with this virtual application pattern. If
IBM Foundation Pattern is upgraded, use the latest version.
Note: You can view a list of which plug-ins are locked if you select
Lock all plugins or Lock all plugins except Foundation plugins. Click
the Source tab in Pattern Builder. The application model source is
displayed. Search for the element plugins to view the list.
5. Design your virtual application template with the components, links, and
policies that you want to include.
6. Click Save.
What to do next
The new application template is now available in the catalog and can be used to
create a virtual application pattern.
Creating virtual applications from templates:
You can use an existing virtual application template to create a virtual application.
These templates are either templates you have already created or is a template that
was shipped with the product.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
About this task
You can deploy a virtual application directly from a template or use it as a starting
point to build a virtual application pattern.
If you do not want to use an existing virtual application template, you can create a
new virtual application template.
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. Select the pattern type associated with the template or search for the template
in the left pane.
3. Select an existing template.
4. Click Open on the toolbar to edit the template.
5. Edit the virtual application pattern component parts:
a. Click the virtual application pattern listed in the left navigation.
b. Click the Open icon in the Virtual Application Pattern pane. The Pattern
Builder displays with the list of virtual application components that you can
drag to the canvas to customize your virtual application pattern.
c. Select a virtual application component and drag the component onto the
canvas to build your virtual application.
Chapter 7. Managing and deploying virtual patterns

511

d. To add a policy, click Add policy for application icon.

e. To create the connection between the parts, hover over one of the objects
until the blue circle turns orange. Select the circle with the left mouse
button, drag a connection to the second object until the object is
highlighted, and release the mouse button.
6. Click Save.
Cloning a virtual application template:
You can clone a virtual application template to create a copy that you can edit and
customize. The template is added to the catalog.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. Select a virtual application template and click the Clone icon on the toolbar.
3. Click OK to confirm that you want to clone the virtual application template.
4. Click Open to name and edit the template.
5. On the Virtual Application properties pane, specify the following information:
Name The name of the virtual application pattern.
Description
(Optional) The description of the virtual application pattern.
Type

Leave Application selected to create a virtual application pattern or

select Template to create a virtual application template that is used as
the basis for creating other virtual application patterns.

Lock option for plugin usage

Specify how this virtual application pattern is affected by upgrades to
the pattern type or to IBM Foundation Pattern.
Unlock plugins
If the pattern type is upgraded use the latest versions of pattern
type plug-ins. If IBM Foundation Pattern is upgraded, use the
latest version.
Lock all plugins
Do not change the version of plug-ins or the version of the IBM
Foundation Pattern associated with this virtual application
pattern when an upgrade occurs.
Lock all plugins except Foundation plugins
If the pattern type is upgraded, do not change the version of
the plug-ins associated with this virtual application pattern. If
IBM Foundation Pattern is upgraded, use the latest version.
Note: You can view a list of which plug-ins are locked if you select
Lock all plugins or Lock all plugins except Foundation plugins. Click
the Source tab in Pattern Builder. The application model source is
displayed. Search for the element plugins to view the list.
6. Click Save.

512

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Editing virtual application templates:

You can edit a virtual application template and use it to create a virtual application
pattern. The template can be saved in the catalog. The virtual application template
is necessary to build your virtual application pattern that is eventually deployed as
a virtual application instance.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. Select a virtual application template. The template details display to the right.
3. Click the Open icon on the toolbar to edit the template. The Pattern Builder
opens.
Importing a virtual application template:
You can import a virtual application template to the IBM Cloud Orchestrator
catalog. The virtual application template is necessary to build your virtual
application pattern that is eventually deployed as a virtual application instance.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
About this task
To import a virtual application template with the user interface:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. Click the Import icon. The Import Application dialogue window opens.
3. Select an application compressed file to import. Click Browse to find the
application file. Your system proceeds to upload the compressed application
file.
Results
You have imported an application template.

Chapter 7. Managing and deploying virtual patterns

513

Exporting a virtual application template:

You can export a virtual application template from the IBM Cloud Orchestrator
catalog. The virtual application template is necessary to build your virtual
application pattern that is eventually deployed as a virtual application instance.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
About this task
To export a virtual application template with the user interface:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. Select an existing template from the left panel of the Virtual Application
Templates palette.
3. Click the Export icon.
Results
You have exported a virtual application template.
Removing a virtual application template:
You can remove a virtual application template from the IBM Cloud Orchestrator
catalog when it is no longer needed.
Before you begin
You must be assigned the catalogeditor role and be granted all access to the
application template to remove. You can also perform these steps if you are
assigned the admin role.
About this task
To remove a virtual application template with the user interface:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. From the Virtual Application Templates palette, select a
virtual_application_template to remove from the catalog.
3. Click the Delete icon to remove the virtual application template from the
catalog. A window displays requesting your confirmation that this application
template can permanently be removed.
4. Click OK to confirm that you want to remove the virtual application template.
Results
The virtual application template has been removed from the catalog.

514

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Working with virtual application pattern plug-ins

Plug-ins provide the constituent parts of a virtual application, as well as the
underlying implementation that makes the application deployable in the cloud.
Pattern types, the containers of solution-specific and topology-specific resources
that are required for different types of virtual applications, are collections of
plug-ins.

About this task

Plug-ins contribute components, links and policies that appear in the Pattern
Builder. They are grouped into pattern types. When a virtual application builder
creates a virtual application pattern, the first step is choosing the pattern type. This
choice determines the options and the user experience in the Pattern Builder. In the
Pattern Builder, virtual application builders can select from the components, links
and policies that the plug-ins in the pattern type expose. The plug-in that
contributes a component or link completely determines its semantics and
operation. Components, links and policies are the most user-visible capabilities a
plug-in can contribute, but there are other capabilities that a plug-in developer
must include. Plug-ins are responsible for the implementation of components and
links when a virtual application is deployed, and maintenance through the entire
lifecycle of the virtual application. A plug-in must contribute proper lifecycle
scripts to manage the virtual application through its various lifecycle events.
A pattern type is a collection of plug-ins that are designed for a specific type of
virtual application pattern and used as the foundation of a virtual application. For
example, a web application uses the IBM Web Application Pattern (not released
with the product), and a database uses the IBM Database Application Patterns (not
released with the product). When a user selects a pattern type in the Pattern
Builder, the design experience is determined by the associated plug-ins. Pattern
types are purchasable at the IBM PureSystems Centre.
You can work with plug-ins as follows:
v Use an existing plug-in to create or extend a virtual application.
v Developing plug-ins to create or extend a virtual application.

Managing system plug-ins

IBM Cloud Orchestrator includes a set of preinstalled system plug-ins. These
plug-ins contain the necessary code for component parts when building virtual
application patterns. The plug-in controls the end-to-end processing and
implementation of the component parts that you use to build the virtual
application pattern. Plug-ins also contribute components, links, and policies that
you can choose to customize your virtual application pattern.

Before you begin

To manage a plug-in, you must be assigned the admin role.
Important: A plug-in is disabled if any of its attributes (configuration parameters)
are not specified.

About this task

You can use either the user interface, the command-line interface, or the REST API
to manage your plug-ins.

Chapter 7. Managing and deploying virtual patterns

515

To learn more about using the command-line interface see command-line interface.
After setting up system plug-ins, you can build a virtual application pattern with
component parts or edit an existing virtual application pattern. After enablement
by the administrator, you can select the specified version and list all the plug-ins
with the IBM version level, release, modification and fix level (v.r.m.f) structure
format.
Plug-ins shipped with pattern types:
Several preinstalled system plug-ins are available with the Foundation pattern type
shipped with IBM Cloud Orchestrator pattern types. You can use these plug-ins to
extend the function of virtual applications.
In the IBM Cloud Orchestrator user interface, click PATTERNS > Deployer
Configuration > System Plug-ins and select the Foundation pattern type to see a
list of the related plug-ins.
In the Pattern Builder, components are grouped into categories.
Adding system plug-ins to the catalog:
You can add a plug-in to the catalog. Plug-ins define components, links, and
policies for virtual application patterns.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
Attention:

Plug-ins are disabled when configurations are not completed.

Procedure
1. Open the IBM Cloud Orchestrator user interface.
2. Click PATTERNS > Deployer Configuration > System Plug-ins.
3. Select the Add icon to upload the plug-in .tgz file. A dialogue box displays
where you can browse for a plug-in .tgz file to import.
Important: If the .tgz file is more than 2 GB, use the command-line interface
to upload the plug-in file to your system.
Deleting plug-ins from the catalog:
You can remove a plug-in from the catalog when a it is no longer needed.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
Procedure
1. Open the IBM Cloud Orchestrator user interface.
2. Click PATTERNS > Deployer Configuration > System Plug-ins.
3. Select the Delete icon to delete the plug-in file. A window displays requesting
confirmation that you want to remove the plug-in.

516

IBM Cloud Orchestrator 2.4.0.2: User's Guide

4. Click OK to confirm that you want to remove the plug-in.

Virtual application pattern components

A virtual application pattern contains components that represent middleware
services that are required by the virtual appliance instance.
You can connect components in a virtual application pattern to indicate
dependencies and optionally apply a policy to configure middleware services
during deployment to configure specific behavior or define a quality of service
level. Components, links, and policies can have required and optional attributes.
Components, links, and policies are defined by plug-ins. When you create a virtual
application pattern, the available components, links, policies, and configuration
options are determined by the plug-ins that are included with the selected pattern
type.
Note: Not all patterns might work for all Hypervisors.
The virtual application pattern was tested successfully on the following operating
systems:
v WebSphere Application Server 8.5.5.1.
v WebSphere Application Server 8.5.0.2.
v DB2 10.5.

Components
The following components are available with the virtual application patterns
provided with IBM Cloud Orchestrator or purchasable at the IBM PureSystems
Centre.
Important: Components that require disk add-ons are not supported in IBM Cloud
Orchestrator.
v Application
Additional archive file
Enterprise application
Existing web service provider endpoint on page 525
Policy set on page 526
Web application, such as IBM WebSphere Application Server
v Database
Data Studio web console
Database, such as IBM DB2
Existing database (DB2) on page 536
Existing database (Informix)
Existing database (Oracle)
Existing IMS database on page 541
v Messaging
Existing Messaging Service (WebSphere MQ) on page 553
Existing queue (WebSphere MQ) on page 556
Existing topic (WebSphere MQ) on page 555
v OSGi
External OSGi bundle repository
Chapter 7. Managing and deploying virtual patterns

517

 OSGi application
v Transaction Processing
CICS Transaction Gateway.
Existing IMS TM on page 565.
v User Registry
Existing User Registry (IBM Tivoli Directory Server) on page 542
Existing User Registry (Microsoft Active Directory) on page 546
User Registry (Tivoli Directory Server) on page 549
v Other components
Generic target
Debug on page 609

Policies
You can optionally apply policies to a virtual application to configure specific
behavior in the deployed virtual application instance. Two virtual applications
might include identical components, but require different policies to achieve
different service level agreements. For example, if you want a web application to
be highly available, you can add a scaling policy to the web application component
and specify requirements such as a processor usage threshold to trigger scaling of
the web application. At deployment time, the topology of the virtual application is
configured to dynamically scale the web application. Multiple WebSphere
Application Server instances are deployed initially for the web application and
instances are added and removed automatically based on the service levels that are
defined in the policy.
Policies can be applied only to particular types of components. For more
information, see the following links:
v Scaling policy
v Routing policy
v Java virtual machine (JVM) policy
v Log policy
Application components:
There are several application components to choose from when building a virtual
application pattern.
About this task
v Additional archive file on page 519
v Enterprise application component on page 520
v Existing web service provider endpoint on page 525
v Policy set on page 526
v Web application component on page 528

518

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Additional archive file:

The additional archive file component is for your primary archive.
Before you begin
The following is a required attribute for a additional archive file:
v Additional archive file: Specifies the external archive file that contains
additional files needed by the web archive (WAR) or enterprise archive (EAR)
file.
v Extraction path: Specifies the extraction path for the additional archive file. This
path must not be an existing path.
Table 42. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web archive (WAR
files).

v Provider policy set binding

v Service name
v Binding file
v Key store
v Trust store (encryption)
v Trust store (digital
signature)

Enterprise application
(WebSphere Application
Server)

An enterprise application
(WebSphere Application
Server) cloud component
represents an execution
service for Java EE enterprise
archive (EAR files).

v Provider policy set binding

v Service name
v Binding file
v Key store
v Trust store (encryption)
v Trust store (digital
signature)

About this task

You can view, edit or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing archive file component, select the Additional archive file
component part on the Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new archive file component to a virtual application pattern, click the
Additional archive file component listed under the Application Component
and drag the icon to the Pattern Builder canvas. The properties panel for the
component displays to the right of the Pattern Builder palette. For more details
on the properties panel settings, view the help by selecting the help icon on the
properties panel.
Chapter 7. Managing and deploying virtual patterns

519

6. You can also view the additional archive file component properties by viewing
the plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select file/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Enterprise application component:
The enterprise application (WebSphere Application Server) component represents
an execution service for Java Platform, Enterprise Edition (Java EE) enterprise
application (EAR) files.
Before you begin
Attention: You cannot use an enterprise application that includes Container
Managed Persistence V 2.0 beans. This type of application requires deploy tools
that are not included in this products WebSphere Application Server binary files .
The following are attributes for an enterprise application:
v EAR file: Specifies the enterprise archive (.ear) file to be uploaded. This
attribute is required.
v Total transaction lifetime timeout: Specifies the default maximum time, in
seconds, allowed for a transaction that is started on this server before the
transaction service initiates timeout completion. Any transaction that does not
begin completion processing before this timeout occurs is rolled back. The
default is 120 seconds.
v Asynchronous response timeout: Specifies the amount of time, in seconds, that
the server waits for responses to WS-AT protocol messages. The default is 120
seconds.
v Client inactivity timeout: Specifies the maximum duration, in seconds, between
transactional requests from a remote client. Any period of client inactivity that
exceeds this timeout results in the transaction being rolled back in this
application server. The default is 60 seconds.
v Maximum transaction timeout: Specifies, in seconds, the maximum transaction
timeout for transactions that run in this server. This value is greater than, or
equal to, the value specified for the total transaction timeout. The default is 300
seconds.
v Iterim fixes URL: Specifies the location or URL of the selected interim fixes. This
URL is used by the WebSphere Application Server virtual machine to download
interim fixes for update.
Policies

520

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 43. Policy components for enterprise applications

Policy name

Description

Scaling policy (web or enterprise

application)

Scaling is a run time capability to

automatically scale your application
platform as the load changes. A scaling
policy component defines this capability and
the conditions under which scaling activities
are performed for your application.

Routing policy (web, enterprise, or OSGi

Routing policy for a web application,
enterprise bundle archive (EBA) application) enterprise application, or an OSGi EBA
application.
Log policy (web or enterprise application)

A policy to specify configuration for log

record files.

JVM policy (web or enterprise application)

A policy to control features of the

underlying Java Virtual Machine (JVM).

Table 44. Incoming connectable components

Component name

Description

Enterprise application (WebSphere

Application Server)

An enterprise application, such as a

WebSphere Application Server application,
cloud component represents an execution
service for Java EE enterprise applications
(EAR) files.

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java EE
web applications (WAR) files.

System updates

System updates for download and update

on the virtual machine.

Table 45. Outgoing connectable components

Component name

Description

Connection

Existing Topic (WebSphere

MQ)

An existing topic represents a v Java Naming and

message destination on an
Directory Interface (JNDI)
external IBM WebSphere MQ
name
messaging service through
v Resource environment
which messages are
references
published and subscribed.
v Message destination
references

Additional archive file

An additional archive file

component for your primary
archive.

Existing messaging service

(WebSphere MQ)

A messaging service
v JNDI name of the Java
represents a connection to an
Message Service (JMS)
external messaging system
connection factory
such as WebSphere MQ.
v Resource references of the
JMS connection factory
v Client ID

Policy set

A component used to define

quality of service policies.

Chapter 7. Managing and deploying virtual patterns

521

Table 45. Outgoing connectable components (continued)

Component name

Description

Connection

Existing database (Oracle)

An existing Oracle database

component represents a
connection to an existing
Oracle database instance
running remotely outside of
the cloud. The configuration
properties allow a connection
to be made to the remote
Oracle database.

Generic target

A component used to open

the firewall for outbound
TCP connections from a web
or enterprise application to a
specified host and port.

Database (DB2)

A database (DB2) component v JNDI name of the data

that represents a
source
pattern-deployed database
v Resource references of the
service.
data source
v Non-transactional data
source
v Minimum connections
v Maximum connections
v Connection timeout

Existing database (DB2)

An existing DB2 database

component represents a
connection to a remote DB2
database instance running
remotely outside of the
cloud. The configuration
properties allow a connection
to be made to the remote
DB2 database.

Existing database (Informix) An existing Informix

database component
represents a connection to a
remote Informix database
instance running remotely
outside of the cloud. The
configuration properties
allow a connection to be
made to the remote Informix
database.

522

Existing CICS Transaction

Gateway (CTG)

An existing CTG component

represents a connection to an
existing CTG instance
running remotely outside of
the cloud. The configuration
properties allow a connection
to be made to the CTG.

Existing IMS database

Existing Information
Management Systems (IMS)
database system.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 45. Outgoing connectable components (continued)

Component name

Description

Connection

Existing user registry (IBM

Tivoli Directory Server)

An existing user registry,

such as Lightweight
Directory Access Protocol
(LDAP), cloud component
represents a
pattern-deployed LDAP
service that can be deployed
by itself or attached to a web
application component or an
enterprise application
component. The LDAP
service provides a user
registry for
container-managed security.

v User filter

Existing user registry

(Microsoft Active Directory)

An existing user registry,

such as LDAP, represents an
existing LDAP service that
can be attached to a web
application component or an
enterprise application
component. The LDAP
service provides a user
registry for container
managed security.

User registry (Tivoli

Directory Server)

A user registry, such as Tivoli

Directory Server, cloud
component represents a
pattern-deployed LDAP
service that can be deployed
by itself or attached to a web
application component or an
enterprise application
component. The LDAP
service provides a user
registry for
container-managed security.

Existing IMS TM

Existing IMS Transaction

Manager (IMS TM)

Enterprise application
(WebSphere Application
Server)

A web application, such as a

WebSphere Application
Server application, cloud
component represents an
execution service for Java EE
enterprise applications (EAR
files).

Web application (WebSphere

Application Server)

A web application, such as a

WebSphere Application
Server application, cloud
component represents an
execution service for Java EE
web applications (WAR files).

v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

Existing web service provider A web service provider

endpoint
provided by a remote server.

Chapter 7. Managing and deploying virtual patterns

523

Table 45. Outgoing connectable components (continued)

Component name

Description

Connection

Existing queue (WebSphere

MQ)

A message queue on an
v JNDI name
external WebSphere MQ
v Resource environment
messaging service through
references
which messages are sent and
v Message destination
received.
references

To make a connection between a component and the enterprise application, hover

over the blue circle on the enterprise application component part on the canvas.
When the blue circle turns yellow, draw a connection between the enterprise
application and component.
Use the property panel to upload the EAR files. To make associations with other
services, create a link to the corresponding virtual application pattern component.
At this time, support is limited to one database and one user registry connection. A
scaling policy object might be attached to specify a highly available pattern.
CAUTION: When using an enterprise application to deploy a database
component, you define the database schema in the SQL file. Do not add the
"connect to <dbname>" statement in the SQL file. The schema object that is used is
db2inst1 and not appuser.
In addition to uploading your EAR file, you can upload additional files, such as a
compressed file containing configuration details or other information. When the
WebSphere process starts, the compressed file is extracted to a directory and the
icmp.external.directory system property is set. If you attach a scaling policy to
the web application component, each virtual machine contains a copy of the
compressed file, and any updates made to the file or directory on one virtual
machine are not reflected in the copy of the file on another virtual machine.
By default, the application is available at http://{ip_address}/{context_root},
where:
v {ip_address} is obtained from the list of deployed cloud applications
v {context_root} is specified within the EAR file.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing enterprise application component, select the Enterprise
Application component part on the Pattern Builder canvas. The properties
panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.

524

IBM Cloud Orchestrator 2.4.0.2: User's Guide

5. To add a enterprise application component to a virtual application pattern, click

the Enterprise Application component listed under the Application
Components and drag the icon to the Pattern Builder canvas. The properties
panel for the component displays to the right of the Pattern Builder palette. For
more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
6. You can also view the enterprise application component properties by viewing
the plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select was/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Existing web service provider endpoint:
A web service provider endpoint is a web service provider that is provided by
remote server.
Before you begin
Important: To use the Web service plug-in in IBM Cloud Orchestrator, the web
service client must be updated as follows:
1. Include the Web service WSDL file in the application package. The WSDL file is
located in WEB-INF/wsdl directory.
2. Update the Web service client source code to specify the location of the WSDL
file. For example: "file:/WEB-INF/wsdl/{WSDL_FILE_NAME}"
The following is a required attribute for a Web service provider endpoint
component:
v Host (IP): Specifies the Host IP of the remote server.
v Port: Specifies the port of remote server.
Connections
Table 46. Incoming connectable components
Component name

Description

Connection properties

Enterprise application
(WebSphere Application
Server)

An enterprise application
(WebSphere Application
Server) cloud component
represents an execution
service for Java Platform,
Enterprise Edition (Java EE)
enterprise archive (EAR
files).

v Service name

Web application (WebSphere

Application Server)

A web application
(WebSphere Application
Server) cloud component
represents an execution
service for Java EE web
archive (WAR files).

v Service name

Chapter 7. Managing and deploying virtual patterns

525

To make a connection between a component and the enterprise application, hover

over the blue circle on the enterprise application component part on the canvas.
When the blue circle turns yellow, draw a connection between the enterprise
application and component.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing enterprise application component, select the Existing Web
Service Provider Endpoint component part on the Pattern Builder canvas. The
properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a the existing Web service provider endpoint component to a virtual
application pattern, click the Existing Web Service Provider Endpoint
component listed under the Application Components and drag the icon to the
Pattern Builder canvas. The properties panel for the component displays to the
right of the Pattern Builder palette. For more details on the properties panel
settings, view the help by selecting the help icon on the properties panel.
6. You can also view the enterprise application component properties by viewing
the plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select webservice/x.x.x.x from the System Plug-ins palette where
x.x.x.x corresponds to the version numbers. The component plug-in
configuration information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Policy set:
A policy set is a component that is used to define quality of service (QoS) policies.
It is a collection of assertions about how services are defined, which can be used to
simplify security configurations.
Before you begin
For more details about policy sets in IBM WebSphere Application Server, see the
WebSphere Application Server Information Center. Refer to the topics, Managing
policy sets using the administrative console, and Exporting policy sets using the
administrative console. The required policy set zip files can be retrieved export
topic.
The following is a required attribute for a policy set component:
v Policy Set File: Specifies the policy set file to upload.
Connections

526

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 47. Incoming connectable components

Component name

Description

Connection properties

Enterprise application
(WebSphere Application
Server)

An enterprise application
(WebSphere Application
Server) cloud component
represents an execution
service for Java Platform,
Enterprise Edition (Java EE)
enterprise archive (EAR
files).

v Provider policy set binding

A web application
(WebSphere Application
Server) cloud component
represents an execution
service for Java EE web
archive (WAR files).

v Provider policy set binding

Web application (WebSphere

Application Server)

v Service name
v Binding file
v Key store
v Trust store (encryption)
v Trust store (digital
signature)

v Service name
v Binding file
v Key store
v Trust store (encryption)
v Trust store (digital
signature)

To make a connection between a component and the policy set, hover over the
blue circle on the enterprise application component part on the canvas. When the
blue circle turns yellow, draw a connection between the policy set and component.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing policy set component, select the Policy Set component part
on the Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new policy set component to a virtual application pattern, click the
Policy Set component listed under the Application Components and drag the
icon to the Pattern Builder canvas. The properties panel for the component
displays to the right of the Pattern Builder palette. For more details on the
properties panel settings, view the help by selecting the help icon on the
properties panel.
6. You can also view the policy set component properties by viewing the plug-in
information. Click PATTERNS > Deployer Configuration > System Plug-ins.
Select webservice/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Chapter 7. Managing and deploying virtual patterns

527

Web application component:

The web application component represents an execution service for the Java
Platform, Enterprise Edition (Java EE) web archive (WAR) files.
Before you begin
The following is a required attribute for a web application:
v WAR file: Specifies the web archive (WAR) file to be uploaded. This attribute is
required.
v Context root: Specifies the context root of the web module. The attribute applies
to the WAR file only.
v Interim fixes URL: Specifies the location of the URL of selected interim fixes.
This URL is used by the WebSphere Application Server virtual machine to
download interim fixes.
Policies
Table 48. Policy components for web applications
Policy name

Description

Routing policy (web, enterprise, or OSGi

Routing policy for a web application,
enterprise bundle archive (EBA) application) enterprise application, or an OSGi EBA
application.
Log policy (web or enterprise application)

A policy to specify configuration for log

files.

JVM policy (web or enterprise application)

A policy to control features of the

underlying Java Virtual Machine (JVM).

Scaling policy (web or enterprise

application)

Scaling is a run time capability to

automatically scale your application
platform as the load changes. A scaling
policy component defines this capability and
the conditions under which scaling activities
are performed for your application.

Connections
Table 49. Incoming connectable components

528

Component name

Description

Enterprise application (WebSphere

Application Server)

An enterprise application, such as a

WebSphere Application Server application,
cloud component represents an execution
service for Java EE enterprise applications
(EAR) files.

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java EE
web applications (WAR) files.

System updates

System updates for download and update

on the virtual machine.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 50. Outgoing connectable components

Component name

Description

Connection

Existing Topic (WebSphere

MQ)

An existing topic represents a v Java Naming and

message destination on an
Directory Interface (JNDI)
external IBM WebSphere MQ
name
messaging service through
v Resource environment
which messages are
references
published and subscribed.
v Message destination
references

Additional archive file

An additional archive file

component for your primary
archive.

Existing messaging service

(WebSphere MQ)

A messaging service
v JNDI name of the Java
represents a connection to an
Message Service (JMS)
external messaging system
connection factory
such as WebSphere MQ.
v Resource references of the
JMS connection factory
v Client ID

Policy set

A component used to define

quality of service policies.

Existing database (Oracle)

An existing Oracle database

component represents a
connection to an existing
Oracle database instance
running remotely outside of
the cloud. The configuration
properties allow a connection
to be made to the remote
Oracle database.

Generic target

A component used to open

the firewall for outbound
TCP connections from a web
or enterprise application to a
specified host and port.

Database (DB2)

A database (DB2) component v JNDI name of the data

that represents a
source
pattern-deployed database
v Resource references of the
service.
data source
v Non-transactional data
source
v Minimum connections
v Maximum connections
v Connection timeout

Existing database (DB2)

An existing DB2 database

component represents a
connection to a remote DB2
database instance running
remotely outside of the
cloud. The configuration
properties allow a connection
to be made to the remote
DB2 database.

Chapter 7. Managing and deploying virtual patterns

529

Table 50. Outgoing connectable components (continued)

Component name

Description

Existing database (Informix)

An existing Informix
database component
represents a connection to a
remote Informix database
instance running remotely
outside of the cloud. The
configuration properties
allow a connection to be
made to the remote Informix
database.

Existing CICS Transaction

Gateway (CTG)

An existing CTG component

represents a connection to an
existing CTG instance
running remotely outside of
the cloud. The configuration
properties allow a connection
to be made to the CTG.

Existing Information
Management Systems (IMS)
database

Existing IMS database

system.

Existing user registry (Tivoli

Directory Server)

An existing user registry,

such as Lightweight
Directory Access Protocol
(LDAP), cloud component
represents a
pattern-deployed LDAP
service that can be deployed
by itself or attached to a web
application component or an
enterprise application
component. The LDAP
service provides a user
registry for
container-managed security.

Existing user registry

(Microsoft Active Directory)

530

IBM Cloud Orchestrator 2.4.0.2: User's Guide

An existing user registry,

such as LDAP, represents an
existing LDAP service that
can be attached to a web
application component or an
enterprise application
component. The LDAP
service provides a user
registry for container
managed security.

Connection

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

Table 50. Outgoing connectable components (continued)

Component name

Description

User registry (Tivoli

Directory Server)

A user registry, such as Tivoli

Directory Server, cloud
component represents a
pattern-deployed LDAP
service that can be deployed
by itself or attached to a web
application component or an
enterprise application
component. The LDAP
service provides a user
registry for
container-managed security.

Existing IMS Transaction

Manager

Existing IMS TM

Enterprise application
(WebSphere Application
Server)

An enterprise application,
such as a WebSphere
Application Server
application, cloud component
represents an execution
service for Java EE enterprise
applications (EAR files).

Web application (WebSphere

Application Server)

A web application, such as a

WebSphere Application
Server application, cloud
component represents an
execution service for Java EE
web applications (WAR files).

Connection

Existing web service provider A web service provider

endpoint
provided by a remote server.
Existing queue (WebSphere
MQ)

A message queue on an
v JNDI name
external WebSphere MQ
v Resource environment
messaging service through
references
which messages are sent and
v
Message destination
received.
references

Use the property panel to upload the WAR files. You can also specify a context
root. To make associations with other services, create a link to the corresponding
cloud component. At this time, support is limited to one database and one user
registry connection. A high availability (HA) policy object might be attached to
specify an HA pattern.
In addition to uploading your WAR file, you can upload additional files, such as a
compressed file containing configuration details or other information. When the
WebSphere process starts, the compressed file is extracted to a directory and the
icmp.external.directory system property is set. If you attach an HA policy to the
web application component, each virtual machine contains a copy of the
compressed file, and any updates made to the file or directory on one virtual
machine are not reflected in the copy of the file on another virtual machine.
By default, the application is available at http://{ip_address}/{context_root},
where:
v {ip_address} is obtained from the list of deployed virtual application patterns.
Chapter 7. Managing and deploying virtual patterns

531

v {context_root} is user-specified for WAR files or specified within the enterprise

archive (EAR) file.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the top right corner of the
Pattern Builder palette.
4. To edit an existing web application component, select the Web Application
component part on the Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a web application component to a virtual application pattern, click the
Web Application component listed under the Application Components and
drag the icon to the Pattern Builder canvas. The properties panel for the
component displays to the right of the Pattern Builder palette. For more details
on the properties panel settings, view the help by selecting the help icon on the
properties panel.
6. You can also view the web application component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select was/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Database components:
There are several database components to choose from when building a virtual
application pattern.
About this task
v Database (DB2) on page 534
v
v
v
v
v

532

Existing database (DB2) on page 536

Existing database (Oracle) on page 539
Existing IMS database on page 541
Existing database (Informix) on page 537
Database Studio web console on page 533

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Database Studio web console:

The Database Studio web console component is a database tool included with the
IBM Database Patterns.
Before you begin
The IBM Database Patterns are purchasable at the IBM PureSystems Centre. This
plug-in component is not available on the Pattern Builder unless you have
accepted the license for the IBM Database Patterns.
The following are the attributes for a component:
v Data Studio web console administrator user: Specifies the Data Studio web
console administrator user ID.
v Data Studio web console administrator user password: Specifies Data Studio
web console administrator user password.
To make a connection between an application component and the database, hover
over the blue circle on the Data Studio web console component part on the canvas.
When the blue circle turns yellow, draw a connection between the Data Studio web
console and the application component.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the top right corner of the
Pattern Builder palette.
4. To edit an existing Data Studio web console component, select the Data Studio
web console component part on the Pattern Builder canvas. The properties
panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a Data Studio web console database component to a virtual application
pattern, click the Data Studio web console component listed under the
Database Components and drag the icon to the Pattern Builder canvas. The
properties panel for the component displays to the right of the Pattern Builder
palette. For more details on the properties panel settings, view the help by
selecting the help icon on the properties panel.
6. You can also view the Data Studio web console component properties by
viewing the plug-in information. Click PATTERNS > Deployer Configuration
> System Plug-ins. Select dswc/x.x.x.x from the System Plug-ins palette where
x.x.x.x corresponds to the version numbers. The component plug-in
configuration information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.

Chapter 7. Managing and deploying virtual patterns

533

Database (DB2):
The DB2 database component represents a pattern-deployed database service.
Before you begin
The following are the attributes for a DB2 database component:
v Database name: Specifies the name of the database name that you want to
deploy.
v Database description: Specifies a description of the database that you want to
deploy.
v Purpose: Specifies the purpose for the database. Select Production or
Non-Production. The default value is Production.
v Source:
Select one of the following sources:
Clone from a database image: Specifies a clone from the database image.
Apply database standard: Specifies to apply a database standard.
Settings include:
- Maximum User Data Space (GB):
Specifies the maximum size of the data space, in gigabytes, in the database
that you want to deploy. The default value is 10 GB.
- Workload standards
Specifies the workload standards. Settings include:
v departmental_OLTP: Specifies the departmental OLTP standard. The
workload type is Departmental OLTP.
v dynamic_datamart: Specifies the dynamic data mart standard. The
workload type Dynamic data mart.
- DB2 Compatability Mode:
Specifies the DB2 compatibility mode. Select Default Mode or Oracle Mode.
The default value is Default Mode.
- Schema file:
Specifies the schema file (*.ddl, *.sql) that defines the database schema.
Click Browse to search for the file on your system.
Connections
Table 51. Incoming connectable components

534

Component name

Description

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java
Platform, Enterprise Edition (Java EE) web
applications (WAR files).

Enterprise application (WebSphere

Application Server)

An enterprise application (WebSphere

Application Server) cloud component
represents an execution service for Java EE
enterprise applications (EAR files).

OSGi application (WebSphere Application

Server)

OSGi application on WebSphere Application

Server.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

To make a connection between an application component and the database, hover

over the blue circle on the DB2 database component part on the canvas. When the
blue circle turns yellow, draw a connection between the DB2 database and the
application component.
The application is assumed to use Java Naming and Directory Interface (JNDI)
settings to locate the data source. Specify the JNDI name in the link property
panel. During deployment, the JNDI name is set to the corresponding data source,
and the name must match the name that is coded into the application.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing DB2 database component, select the Database (DB2)
component part on the Pattern Builder canvas. The properties panel is
displayed. For more details on the properties panel settings, view the help by
selecting the help icon on the properties panel.
5. To add a DB2 database component to a virtual application pattern, click the
Database (DB2) component listed under the Database Components and drag
the icon to the Pattern Builder canvas. The properties panel for the component
is displayed to the right of the Pattern Builder palette. For more details on the
properties panel settings, view the help by selecting the help icon on the
properties panel.
CAUTION: When defining the database schema, do not add the "connect to
<dbname>" statement in the SQL file. The schema object that is used is
db2inst1 and not appuser.
6. You can also view the DB2 database component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select db2/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
View the agent log files for troubleshooting. To find the appropriate trace.log file,
navigate to /logs/database-<db_name>.<instanceNumber>.<DB2>.

Chapter 7. Managing and deploying virtual patterns

535

Existing database (DB2):

An existing DB2 database component represents a connection to a remote DB2
database instance running remotely outside of the cloud infrastructure. The
configuration properties allow a connection to be made to the remote DB2
database.
Before you begin
The following are the attributes for a remote DB2 database component:
v Existing database name: Specifies the name of the existing DB2 database. This
attribute is required.
v Server host name or IP: Specifies the server host name or IP address of the
existing DB2 database. This attribute is required.
v Server port number: Specifies the port number of the existing DB2 database.
The default is 50000. This attribute is required.
v User name: Specifies the user name to access the existing DB2 database. This
attribute is required.
v Password: Specifies the password to access the existing DB2 database. This
attribute is required.
Connections
Table 52. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v Java Naming and

Directory Interface (JNDI)
name of the data source

Enterprise application
(WebSphere Application
Server)

v Resource references of the

data source
v Non-transactional data
source

An enterprise application
v JNDI name of the data
(WebSphere Application
source
Server) cloud component
v Resource references of the
represents an execution
data source
service for Java EE enterprise
v
Non-transactional data
applications (EAR files).
source

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server.

v JNDI name of the data

source
v Resource references of the
data source
v Non-transactional data
source

To make a connection between an application component and the remote database,

hover over the blue circle on the DB2 remote database component part on the
canvas. When the blue circle turns yellow, draw a connection between the DB2
remote database and the application component.
The application is assumed to use JNDI settings to locate the data source. Specify
the JNDI name in the link property panel. During deployment, the JNDI name is

536

IBM Cloud Orchestrator 2.4.0.2: User's Guide

set to the corresponding data source, and the name must match the name that is
coded into the application.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing remote DB2 database component, select the Existing
Database component part on the Pattern Builder canvas. The properties panel
displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add an existing DB2 database component to a virtual application pattern,
click the Existing Database (DB2) component listed under the Database
Components and drag the icon to the Pattern Builder canvas. The properties
panel for the component displays to the right of the Pattern Builder palette. For
more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
6. You can also view the remote DB2 database component properties by viewing
the plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select wasdb2/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Existing database (Informix):
An existing Informix database component represents a connection to a remote
Informix database running remotely outside of the cloud infrastructure. The
configuration properties allow a connection to be made to the remote Informix
database.
Before you begin
The following are the attributes for a remote Informix database component:
v Database name: Specifies the name of the existing Informix database. This
attribute is required.
v Server host name or IP address: Specifies the server host name or IP address of
the existing Informix database. This attribute is required.
v Server port number: Specifies the port number of the existing Informix
database. The default is 9088. This attribute is required.
v User name: Specifies the user name to access the existing Informix database.
This attribute is required.

Chapter 7. Managing and deploying virtual patterns

537

v Password: Specifies the password to access the existing Informix database. This
attribute is required.
Connections
Table 53. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v Java Naming and

Directory Interface (JNDI)
name of the data source

Enterprise application
(WebSphere Application
Server)

v Resource references of the

data source
v Non-transactional data
source

An enterprise application
v JNDI name of the data
(WebSphere Application
source
Server) cloud component
v Resource references of the
represents an execution
data source
service for Java EE enterprise
v Non-transactional data
applications (EAR files).
source

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server.

v JNDI name of the data

source
v Resource references of the
data source
v Non-transactional data
source

To make a connection between an application component and the remote database,

hover over the blue circle on the Informix remote database component part on the
canvas. When the blue circle turns yellow, draw a connection between the Informix
remote database and the application component.
The application is assumed to use JNDI settings to locate the data source. Specify
the JNDI name in the link property panel. During deployment, the JNDI name is
set to the corresponding data source, and the name must match the name that is
coded into the application.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing remote Informix database component, select the Existing
Database component part on the Pattern Builder canvas. The properties panel
displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.

538

IBM Cloud Orchestrator 2.4.0.2: User's Guide

5. To add an existing Informix database component to a virtual application

pattern, click the Existing Database (Informix) component listed under the
Database Components and drag the icon to the Pattern Builder canvas. The
properties panel for the component displays to the right of the Pattern Builder
palette. For more details on the properties panel settings, view the help by
selecting the help icon on the properties panel.
6. You can also view the remote Informix database component properties by
viewing the plug-in information. Click PATTERNS > Deployer Configuration
> System Plug-ins. Select wasdb2/x.x.x.x from the System Plug-ins palette
where x.x.x.x corresponds to the version numbers. The component plug-in
configuration information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Existing database (Oracle):
An existing Oracle database component represents a connection to an existing
Oracle database instance running remotely outside of the cloud. The configuration
properties allow a connection to be made to the remote Oracle database.
Before you begin
The following are the attributes for an existing Oracle database component:
v Database name: Specifies the name of the existing Oracle database.
v Server host name or IP address: Specifies the server host name or IP address of
the existing Oracle database server. This attribute is required.
v Server port number: Specifies the port number of the existing Oracle database.
The default is 1521. This attribute is required.
v User name: Specifies the name used to access the existing Oracle database. This
attribute is required.
v Password: Specifies the password associated with the existing Oracle database.
This attribute is required.
Connections
Table 54. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web archive (WAR
files).

v Java Naming and

Directory Interface (JNDI)
name of the data source

Enterprise application
(WebSphere Application
Server)

v Resource references of the

data source
v Non-transactional data
source

An enterprise application
v JNDI name of the data
(WebSphere Application
source
Server) cloud component
v Resource references of the
represents an execution
data source
service for Java EE enterprise
v Non-transactional data
archive (EAR files).
source

Chapter 7. Managing and deploying virtual patterns

539

Table 54. Incoming connectable components (continued)

Component name

Description

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server.

Connection properties
v JNDI name of the data
source
v Resource references of the
data source
v Non-transactional data
source

To make a connection between an application component and the existing Oracle

database, hover over the blue circle on the existing Oracle database component
part on the canvas. When the blue circle turns yellow, draw a connection between
the existing Oracle database and the application component.
The application is assumed to use JNDI settings to locate the data source. Specify
the JNDI name in the link property panel. During deployment, the JNDI name is
set to the corresponding data source, and the name must match the name that is
coded into the application.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing remote Oracle database component, select the Existing
Database (Oracle) component part on the Pattern Builder canvas. The
properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add an existing Oracle database component to a virtual application pattern,
click the Existing Database (Oracle) component listed under the Database
Components and drag the icon to the Pattern Builder canvas. The properties
panel for the component displays to the right of the Pattern Builder palette. For
more details on these the properties panel settings, view the help by selecting
the help icon on the properties panel.
6. You can also view the Oracle database component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select wasoraclex.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.

540

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Existing IMS database:

An Information Management Systems Database IMS DB component represents a
connection to an IMS database instance running remotely outside of the cloud
infrastructure. The configuration properties allow a connection to be made to the
IMS DB system.
Before you begin
The following are the attributes for an IMS database component:
v Resource adapter: Specifies the full path name of the IMS database system
resource adapter. This attribute is required.
v Server host name or IP Address: Specifies the host name or IP address of the
IMS database system. This attribute is required.
v Server Port number: Specifies the port number of the existing IMS database
system. This attribute is required.
v Datastore name: Specifies the name of the target IMS data store. This attribute is
required.
v Metadata URL: Specifies the Java metadata class that provides the database
view of the IMS database. This attribute is required.
v User name: Specifies the name that is used to access the existing IMS database
system.
v Password: Specifies the password associated with the user name property.
The following are optional properties:
Connections
Table 55. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v Java Naming and

Directory Interface (JNDI)
name of the data source

Enterprise application
(WebSphere Application
Server)

v Resource references of the

data source

An enterprise application
v JNDI name of the data
(WebSphere Application
source
Server) cloud component
v Resource references of the
represents an execution
data source
service for Java EE enterprise
applications (EAR files).

To make a connection between an application component and an existing IMS

database, hover over the blue circle on the IMS database component part on the
canvas. When the blue circle turns yellow, draw a connection between the IMS
database and the application component. The application can use JNDI or Resource
references settings to locate the data source. Specify the JNDI name or the Resource
Reference in the link property panel. The name must match the name that is coded
into the application.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Chapter 7. Managing and deploying virtual patterns

541

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To add a new IMS database component to a virtual application pattern, click
the Existing IMS Database component listed under the Databases
Components and drag the icon to the Pattern Builder canvas. The properties
panel for the database component displays to the right of the Pattern Builder
palette. For more details on the properties panel settings, view the help by
selecting the help icon on the properties panel.
5. To edit an existing IMS database component, select the Existing IMS Database
component part on the Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, see the properties descriptions
or view the help by selecting the help icon on the properties panel.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
6. You can also view the database component properties by viewing the plug-in
information. Click PATTERNS > Deployer Configuration > System Plug-ins.
Select imsdb/x.x.x.x from the System Plug-ins palette where x.x.x.x corresponds
to the version numbers. The component plug-in configuration information
displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
User Registry components:
There are several user registry components to choose from when building a virtual
application pattern.
About this task
v Existing User Registry (IBM Tivoli Directory Server)
v Existing User Registry (Microsoft Active Directory) on page 546
v User Registry (Tivoli Directory Server) on page 549
Existing User Registry (IBM Tivoli Directory Server):
An existing user registry cloud component represents an existing Lightweight
Directory Access Protocol (LDAP) service that can be attached to a web application
component or an enterprise application component. The LDAP service provides a
user registry for container-managed security.
Before you begin
The following are attributes for the user registry component:
v Server Hostname or IP address: Specifies the hostname or IP address of the
remote LDAP. This attribute is required.
v Server Port Number: Specifies the port number of the remote LDAP. The default
is 389 or 636 for Secure Socket Layer (SSL). This attribute is required.
v Login domain name (DN): Specifies the login DN. This attribute is required.

542

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Password: Specifies the password to access the remote LDAP. This attribute is
required.
v Domain Suffix of LDAP: Specifies the domain suffix of the remote LDAP. This
attribute is required.
v Server SSL certificate: Specifies the SSL port certificate for the remote LDAP.
v User filter: Specifies the LDAP user filter that searches the existing user registry
for users.
v Group filter: Specifies the LDAP group filter that searches the existing user
registry for groups.
Default settings
Tivoli Directory Server is registered to the federated repository in WebSphere
Application Server using Virtual Member Manager (VMM) with the following
settings:
v Login properties of VMM = uid or cn
v Entity type
Object class of PersonAccount = Person or inetOrgPerson in ITDS
Object class of Group = groupOfUniqueNames or groupOfNames in ITDS
Note: The default value for the object class is groupOfUniqueNames. This value
cannot be changed.
Connections
Table 56. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

Enterprise application
(WebSphere Application
Server)

An enterprise application
(WebSphere Application
Server) cloud component
represents an execution
service for Java EE enterprise
applications (EAR files).

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

To make a connection between an application component and an existing Tivoli

Directory Server user registry, hover over the blue circle on the existing user
registry component part on the canvas. When the blue circle turns yellow, draw a
Chapter 7. Managing and deploying virtual patterns

543

connection between the user registry and component.

About this task
The current implementation supports a one-time upload of users and groups in an
LDAP Data Interchange Format (LDIF) file, and applications are currently limited
to enterprise applications. Within the application, the roles are defined in the
web.xml file. Bindings of roles to users and groups are defined in the
META-INF/ibm-application-bnd.xml file. Bind the roles to group for ease of
management.
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing user registry component, select the component part on the
Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add an existing registry component to a virtual application pattern, click the
Existing User Registry (IBM Tivoli Directory Server) component located
under the User Registry Components and drag the icon to the Pattern Builder
canvas. The properties panel for the component displays to the right of the
Pattern Builder palette. For more details on the properties panel settings, view
the help by selecting the help icon on the properties panel.
6. You can also view the user registry component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select wasldap/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Example
The following examples illustrate the three metadata files that are required to set
up an enterprise application with the user registry component.
The LDIF file defines the users and groups for the application. user2 is in the
group1 group.
dn: o=acme,c=us
objectclass: organization
objectclass: top
o: ACME
dn: cn=user2,o=acme,c=us
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top

544

IBM Cloud Orchestrator 2.4.0.2: User's Guide

objectclass: ePerson
cn: user2
userpassword: user2
initials: user2
sn: user2
uid: user2
dn: cn=group1,o=acme,c=us
objectclass: groupOfNames
objectclass: top
cn: manager
member: cn=user2,o=acme,c=us

The web.xml file defines the roles and security policy for the application. role1 can
only access the protected resources.
<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com
/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<display-name>HitCountWeb</display-name>
<servlet>
<description></description>
<display-name>HitCountServlet</display-name>
<servlet-name>HitCountServlet</servlet-name>
<servlet-class>com.ibm.samples.hitcount.HitCountServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HitCountServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
<security-constraint>
<display-name>AllAuthenticated</display-name>
<web-resource-collection>
<web-resource-name>All</web-resource-name>
<url-pattern>/*</url-pattern>
<http-method>GET</http-method>
<http-method>PUT</http-method>
<http-method>HEAD</http-method>
<http-method>TRACE</http-method>
<http-method>POST</http-method>
<http-method>DELETE</http-method>
<http-method>OPTIONS</http-method>
</web-resource-collection>
<auth-constraint>
<description>Auto generated Authorization Constraint</description>
<role-name>role1</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<realm-name></realm-name>
<form-login-config>
<form-login-page>/login.jsp</form-login-page>
<form-error-page>/login.jsp?error=Invalid+username+or+password</form-error-page>
</form-login-config>
</login-config>
<security-role>
<description>allowed group</description>
<role-name>role1</role-name>
</security-role>
</web-app>

The binding file binds the group1 group to the role1 role.
Chapter 7. Managing and deploying virtual patterns

545

<?xml version="1.0" encoding="UTF-8"?>

<application-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee
http://websphere.ibm.com/xml/ns/javaee/ibm-application-bnd_1_0.xsd"
version="1.0">
<security-role name="role1">
<group name="group1" />
</security-role>
</application-bnd>

Existing User Registry (Microsoft Active Directory):

An existing user registry cloud component represents an existing Lightweight
Directory Access Protocol (LDAP) service that can be attached to a web application
component or an enterprise application component. The LDAP service provides a
user registry for container-managed security.
Before you begin
The following are attributes for the user registry component:
v Server Hostname or IP Address: Specifies the host name or IP address of the
remote LDAP Server. This attribute is required.
v Server Port Number: Port number of the remote LDAP. The default is 389 or 636
for Secure Sockets Layer (SSL). This attribute is required.
v Login domain name (DN): Specifies the login DN. This attribute is required.
v Password: Specifies the password to access the remote LDAP. This attribute is
required.
v Domain suffix of LDAP: Specifies the domain suffix of the remote LDAP. This
attribute is required.
v Server SSL certificate: Specifies the SSL port certificate for the remote LDAP.
v User Filter: Specifies the LDAP user filter that searches the existing user
registry for users.
v

Group Filter: Specifies the LDAP group filter that searches the existing user
registry for groups.

Default settings
Microsoft Active Directory Server is registered to the federated repository in
WebSphere Application Server using Virtual Member Manager (VMM) with the
following settings:
v Login properties of VMM = uid or cn
*samAccountName is mapped to both uid and cn
v Entity type
Object class of PersonAccount = user
Object class of Group = group
Connections

546

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 57. Incoming connectable components

Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web archive (WAR
files).

v Role name

An enterprise application
(WebSphere Application
Server) cloud component
represents an execution
service for Java EE enterprise
archive (EAR files).

v Role name

Enterprise application
(WebSphere Application
Server)

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

v User role mapping

v Group role mapping
v Mapping special subjects

v User role mapping

v Group role mapping
v Mapping special subjects
v Role name
v User role mapping
v Group role mapping
v Mapping special subjects

To make a connection between an application component and an existing Microsoft

Active Directory, hover over the blue circle on the user registry component part on
the canvas. When the blue circle turns yellow, draw a connection between the user
registry and component.
About this task
The current implementation supports a one-time upload of users and groups in an
LDAP Data Interchange Format (LDIF) file, and applications are currently limited
to enterprise applications. Within the application, the roles are defined in the
web.xml file. Bindings of roles to users and groups are defined in the
META-INF/ibm-application-bnd.xml file. Bind the roles to group for ease of
management.
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing user registry component, select the component part on the
Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add an existing Microsoft Active Directory user registry component to a
virtual application pattern, click Existing User Registry (Microsoft Active
Directory) listed under the User Registry Components and drag the icon to the
Pattern Builder canvas. The properties panel for the component displays to the
right of the Pattern Builder palette. For more details on the properties panel
settings, view the help by selecting the help icon on the properties panel.

Chapter 7. Managing and deploying virtual patterns

547

6. You can also view the user registry component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select wasldap/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Example
The following examples illustrate the three metadata files that are required to set
up an enterprise application with the user registry component.
The LDIF file defines the users and groups for the application. user2 is in the
group1 group.
dn: o=acme,c=us
objectclass: organization
objectclass: top
o: ACME
dn: cn=user2,o=acme,c=us
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: ePerson
cn: user2
userpassword: user2
initials: user2
sn: user2
uid: user2
dn: cn=group1,o=acme,c=us
objectclass: groupOfNames
objectclass: top
cn: manager
member: cn=user2,o=acme,c=us

The web.xml file defines the roles and security policy for the application. role1 can
only access the protected resources.
<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com
/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<display-name>HitCountWeb</display-name>
<servlet>
<description></description>
<display-name>HitCountServlet</display-name>
<servlet-name>HitCountServlet</servlet-name>
<servlet-class>com.ibm.samples.hitcount.HitCountServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HitCountServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
<security-constraint>
<display-name>AllAuthenticated</display-name>
<web-resource-collection>
<web-resource-name>All</web-resource-name>
<url-pattern>/*</url-pattern>

548

IBM Cloud Orchestrator 2.4.0.2: User's Guide

<http-method>GET</http-method>
<http-method>PUT</http-method>
<http-method>HEAD</http-method>
<http-method>TRACE</http-method>
<http-method>POST</http-method>
<http-method>DELETE</http-method>
<http-method>OPTIONS</http-method>
</web-resource-collection>
<auth-constraint>
<description>Auto generated Authorization Constraint</description>
<role-name>role1</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<realm-name></realm-name>
<form-login-config>
<form-login-page>/login.jsp</form-login-page>
<form-error-page>/login.jsp?error=Invalid+username+or+password</form-error-page>
</form-login-config>
</login-config>
<security-role>
<description>allowed group</description>
<role-name>role1</role-name>
</security-role>
</web-app>

The binding file binds the group1 group to the role1 role.
<?xml version="1.0" encoding="UTF-8"?>
<application-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee
http://websphere.ibm.com/xml/ns/javaee/ibm-application-bnd_1_0.xsd"
version="1.0">
<security-role name="role1">
<group name="group1" />
</security-role>
</application-bnd>

User Registry (Tivoli Directory Server):

A user registry (Tivoli Directory Server) cloud component represents a
pattern-deployed Lightweight Directory Access Protocol (LDAP) service that can be
deployed by itself or attached to a web application component or an enterprise
application component. The LDAP service provides a user registry for
container-managed security.
Before you begin
The following are attributes for the user registry component:
v Base domain name (DN): Specifies the base DN. This attribute is required.
v LDIF file: Specifies the name of the LDAP Data Interchange Format (LDIF) file.
This attribute is required.
v Custom schema file: Specifies the name of the custom schema file.
v User filter: Specifies the LDAP user filter that searches the existing user registry
for users. This attribute is required.

Chapter 7. Managing and deploying virtual patterns

549

v Group filter: Specifies the LDAP group filter that searches the existing user
registry for groups. This attribute is required.
Default settings
Tivoli Directory Server is registered to the federated repository in WebSphere
Application Server using Virtual Member Manager (VMM) with the following
settings:
v Login properties of VMM = uid or cn
v Entity type
Object class of PersonAccount = Person or inetOrgPerson in ITDS
Object class of Group = groupOfUniqueNames or groupOfNames in ITDS
Note: The default value for the object class is groupOfUniqueNames. This value
cannot be changed.
Connections
Table 58. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

Enterprise application
(WebSphere Application
Server)

An enterprise application
(WebSphere Application
Server) cloud component
represents an execution
service for Java EE enterprise
applications (EAR files).

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

To make a connection between a component and the user registry, hover over the
blue circle on the user registry component part on the canvas. When the blue circle
turns yellow, draw a connection between the user registry and component.
About this task
The current implementation supports a one-time upload of users and groups in an
LDIF file, and applications are currently limited to enterprise applications. Within
the application, the roles are defined in the web.xml file. Bindings of roles to users
and groups are defined in the META-INF/ibm-application-bnd.xml file. Bind the
roles to group for ease of management.

550

IBM Cloud Orchestrator 2.4.0.2: User's Guide

You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing user registry component, select the component part on the
Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a user registry component to a virtual application pattern, click User
Registry (Tivoli Directory Server) listed under the User Registry Components
and drag the icon to the Pattern Builder canvas. The properties panel for the
component displays to the right of the Pattern Builder palette. For more details
on the properties panel settings, view the help by selecting the help icon on the
properties panel.
6. You can also view the user registry component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select tds/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Example
The following examples illustrate the three metadata files that are required to set
up an enterprise application with the user registry component.
The LDIF file defines the users and groups for the application. user2 is in the
group1 group.
dn: o=acme,c=us
objectclass: organization
objectclass: top
o: ACME
dn: cn=user2,o=acme,c=us
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: ePerson
cn: user2
userpassword: user2
initials: user2
sn: user2
uid: user2
dn: cn=group1,o=acme,c=us
objectclass: groupOfNames
objectclass: top
cn: manager
member: cn=user2,o=acme,c=us

Chapter 7. Managing and deploying virtual patterns

551

The web.xml file defines the roles and security policy for the application. role1 can
only access the protected resources.
<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com
/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<display-name>HitCountWeb</display-name>
<servlet>
<description></description>
<display-name>HitCountServlet</display-name>
<servlet-name>HitCountServlet</servlet-name>
<servlet-class>com.ibm.samples.hitcount.HitCountServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HitCountServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
<security-constraint>
<display-name>AllAuthenticated</display-name>
<web-resource-collection>
<web-resource-name>All</web-resource-name>
<url-pattern>/*</url-pattern>
<http-method>GET</http-method>
<http-method>PUT</http-method>
<http-method>HEAD</http-method>
<http-method>TRACE</http-method>
<http-method>POST</http-method>
<http-method>DELETE</http-method>
<http-method>OPTIONS</http-method>
</web-resource-collection>
<auth-constraint>
<description>Auto generated Authorization Constraint</description>
<role-name>role1</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<realm-name></realm-name>
<form-login-config>
<form-login-page>/login.jsp</form-login-page>
<form-error-page>/login.jsp?error=Invalid+username+or+password</form-error-page>
</form-login-config>
</login-config>
<security-role>
<description>allowed group</description>
<role-name>role1</role-name>
</security-role>
</web-app>

The binding file binds the group1 group to the role1 role.
<?xml version="1.0" encoding="UTF-8"?>
<application-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee
http://websphere.ibm.com/xml/ns/javaee/ibm-application-bnd_1_0.xsd"
version="1.0">
<security-role name="role1">
<group name="group1" />
</security-role>
</application-bnd>

552

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Messaging components:
There are several message components to choose from when building a virtual
application pattern.
About this task
v Existing Messaging Service (WebSphere MQ)
v Existing topic (WebSphere MQ) on page 555
v Existing queue (WebSphere MQ) on page 556
Existing Messaging Service (WebSphere MQ):
An existing message service component represents a connection to an external
messaging system such as WebSphere MQ. The presence of a messaging system
allows an enterprise application running on WebSphere Application Server to
connect to the external messaging resource, such as WebSphere MQ.
Before you begin
The following are attributes for the messaging service:
v Queue manager name: Specifies the name of the queue manager to connect to.
This attribute is required.
v Server host name or IP address: Specifies the TCP/IP host name or address of
the external WebSphere MQ messaging service. This attribute is required.
v Server Port Number: Specifies the TCP/IP port on which the external
WebSphere MQ message service is listening for connections. This attribute is
required. The default port is 1414.
v Channel name: Specifies the name of the channel definition to use when
accessing the WebSphere MQ queue manager. This attribute is required. The
default is SYSTEM.DEF.SVRCONN.
Connections
Table 59. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v Java Naming Directory

Interface (JNDI) name of
JMS connection factory

Enterprise application
(WebSphere Application
Server)

v Resource references of JMS

connection factory
v Client ID

An enterprise application
v JNDI Name of JMS
(WebSphere Application
connection factory
Server) cloud component
v Resource references of JMS
represents an execution
connection factory
service for Java EE enterprise
v Client ID
applications (EAR files).

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

v JNDI Name of JMS

connection factory
v Resource references of JMS
connection factory
v Client ID

Chapter 7. Managing and deploying virtual patterns

553

The application is assumed to use JNDI settings to locate the topic. Specify the
JNDI name in the link property panel, either as a hard-coded JNDI name or by
selecting the relevant application resource-references from the property panel list
box. During deployment, the JNDI name is set to the corresponding topic, and
mapped, if required, to the relevant resource reference in the application.
To make a connection between an application component and the messaging
service, hover over the blue circle on the messaging service component part on the
canvas. When the blue circle turns yellow, draw a connection between the
messaging service and application component.
About this task
The messaging service component represents a connection to an instance of IBM
WebSphere MQ. The component can be configured to create a connection to your
IBM WebSphere MQ installation. When you click the messaging service component
on the Pattern Builder canvas, a properties panel displays.
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing messaging service component, select the component part on
the Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a messaging service component to a virtual application pattern, click
Existing Messaging Service (WebSphere MQ) listed under the Messaging
Components and drag the icon to the Pattern Builder canvas. The properties
panel for the transaction processing component displays to the right of the
Pattern Builder palette. For more details on the properties panel settings, view
the help by selecting the help icon on the properties panel.
6. You can also view the existing WebSphere MQ service properties by viewing
the plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select wasmqx/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.

554

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Existing topic (WebSphere MQ):

A topic represents a message destination on an external WebSphere MQ messaging
service through which messages are published and subscribed.
Before you begin
The following is a required attribute for topic:
v Existing topic name: Specifies the name of the topic destination on the external
WebSphere MQ messaging service through which messages are published and
subscribed.
Connections
Table 60. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v JNDI name

Enterprise application
(WebSphere Application
Server)

v Resource environment
references
v Message destination
references

An enterprise application
v JNDI name
(WebSphere Application
v Resource environment
Server) cloud component
references
represents an execution
service for Java EE enterprise v Message destination
references
applications (EAR files).

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

v JNDI name
v Resource environment
references
v Message destination
references

The application is assumed to use JNDI settings to locate the topic. Specify the
JNDI name in the link property panel, either as a hard-coded JNDI name or by
selecting the relevant application resource-references from the property panel list
box. During deployment, the JNDI name is set to the corresponding topic, and
mapped, if required, to the relevant resource reference in the application.
The required attributes for Link to WebSphere MQ topic are as follows:
v JNDI name: The JNDI name that the application uses to locate the topic
destination. The JNDI name is only required if the application accesses the topic
directly without using a resource environment reference or message destination
reference.
v Resource environment references: The resource environment references that the
application uses to locate the topic.
v Message destination references: The message destination references that the
application uses to locate the topic.
To make a connection between a component and the messaging topic, hover over
the blue circle on the topic component part on the canvas. When the blue circle
turns yellow, draw a connection between the topic and component.
Chapter 7. Managing and deploying virtual patterns

555

About this task

You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual application pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing topic, select the Existing Topic component part on the
Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add an existing topic component to a virtual application pattern, click the
Existing Topic component listed under the Messaging Components component
and drag the icon to the Pattern Builder canvas. The properties panel for the
component displays to the right of the Pattern Builder palette. For more details
on the properties panel settings, view the help by selecting the help icon on the
properties panel.
6. You can also view the topic component properties by viewing the plug-in
information. Click PATTERNS > Deployer Configuration > System Plug-ins.
Select wasmqt/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Existing queue (WebSphere MQ):
An existing message queue is a message queue on an external WebSphere MQ
service from which messages are sent and received.
Before you begin
The following is a required attribute for a queue:
v Existing queue name: Specifies the name of the message queue on the external
WebSphere MQ messaging service through which messages are sent and
received.
Connections
Table 61. Incoming connectable components

556

Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v JNDI name

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Resource environment
references
v Message destination
references

Table 61. Incoming connectable components (continued)

Component name

Description

Enterprise application
(WebSphere Application
Server)

An enterprise application
v JNDI name
(WebSphere Application
v Resource environment
Server) cloud component
references
represents an execution
service for Java EE enterprise v Message destination
references
applications (EAR files).

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

Connection properties

v JNDI name
v Resource environment
references
v Message destination
references

The application is assumed to use JNDI settings to locate the queue. Specify the
JNDI name in the link property panel, either as a hard-coded JNDI name or by
selecting the relevant application resource-references from the property panel list
box. During deployment, the JNDI name is set to the corresponding queue, and
mapped if required to the relevant resource reference in the application.
The required attributes for Link to WebSphere MQ queue are as follows:
v JNDI name: The JNDI name that the application uses to locate the queue
destination. This is only required if the application accesses the queue directly
without using a resource environment reference or message destination
reference.
v Resource environment references: The resource environment references that the
application uses to locate the Queue.
v Message destination references: The message destination references that the
application uses to locate the Queue.
To make a connection between a component and the messaging queue, hover over
the blue circle on the queue component part on the canvas. When the blue circle
turns yellow, draw a connection between the queue and component.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing queue, select the Existing Queue component part on the
Pattern Builder canvas. The properties panel displays.
For more details on these the properties panel settings, view the help by
selecting the help icon on the properties panel.
5. To add a new queue component to a virtual application pattern, click the
Existing Queue (WebSphere MQ) component listed under the Messaging
Components and drag the icon to the Pattern Builder canvas. The properties

Chapter 7. Managing and deploying virtual patterns

557

panel for the component displays to the right of the Pattern Builder palette. For
more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
6. You can also view the queue component properties by viewing the plug-in
information. Click PATTERNS > Deployer Configuration > System Plug-ins.
Select wasmqq/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
OSGi components:
The OSGi components available as parts for your virtual application pattern are
the OSGi application and the external OSGi bundle repository.
About this task
v Existing OSGi bundle repository (WebSphere Application Server)
v OSGi application (WebSphere Application Server) on page 559
Existing OSGi bundle repository (WebSphere Application Server):
This component provides the URL of an existing WebSphere Application Server
OSGi bundle repository.
Before you begin
The following are the attributes for the external OSGi bundle repository:
v Bundle repository URL: Specifies the URL of the existing OSGi bundle
repository. This attribute is required.
Connections
Table 62. Incoming connectable components
Component name

Description

OSGi application (WebSphere Application

Server)

OSGi application on WebSphere Application

Server

To make a connection between an OSGi application component and the external

OSGi bundle repository, hover over the blue circle on the external OSGi bundle
repository component part on the canvas. When the blue circle turns yellow, draw
a connection between the external OSGi bundle repository and OSGi application
component.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.

558

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing external OSGi bundle repository component, select the
External OSGi Bundle Repository component part on the Pattern Builder
canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add an external OSGi bundle repository component to a virtual application
pattern, click the External OSGi Bundle Repository component listed under
the OSGi Components and drag the icon to the Pattern Builder canvas. The
properties panel for the component displays to the right of the Pattern Builder
palette. For more details on the properties panel settings, view the help by
selecting the help icon on the properties panel.
6. You can also view the external OSGi bundle repository component properties
by viewing the plug-in information. Click PATTERNS > Deployer
Configuration > System Plug-ins. Select osgirepo/x.x.x.x from the System
Plug-ins palette where x.x.x.x corresponds to the version numbers. The
component plug-in configuration information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
OSGi application (WebSphere Application Server):
This component represents the OSGi application on WebSphere Application Server.
Before you begin
The following are attributes for the OSGi application component:
v EBA file: Specifies the OSGi application to be uploaded. The OSGi application is
an enterprise bundle archive (EBA) file (.eba). This attribute is required.
Connections
Table 63. Incoming connectable components
Component name

Description

Scaling policy (web or enterprise

application)

Scaling is a workload pattern runtime

capability to automatically scale your
application platform as the load changes. A
scaling policy component defines this
capability and the conditions under which
scaling activities are performed for your
application.

Routing policy (web, enterprise, or OSGi

EBA application)

Specifies a routing policy for a web

application, enterprise application, or an
OSGi EBA application.

Log policy (web or enterprise application)

A policy to specify configuration for log file

records.

JVM policy (web or enterprise application)

A policy to control features of the

underlying Java Virtual Machine (JVM).

Chapter 7. Managing and deploying virtual patterns

559

Table 64. Outgoing connectable components

Component name

Description

Connection

Existing Topic (WebSphere

MQ)

An existing topic represents v Java Naming and

a message destination on an
Directory Interface (JNDI)
external IBM WebSphere MQ
name
messaging service through
v Resource environment
which messages are
references
published and subscribed.
v Message destination
references

Existing Messaging service

(WebSphere MQ)

An existing messaging
service represents a
connection to an external
messaging system such as
WebSphere MQ.

v JNDI name of the Java

Message Service (JMS)
connection factory
v Resource references of the
JMS connection factory
v Client ID

Existing Database (Oracle)

An existing Oracle database

component represents a
connection to an existing
Oracle database instance
running remotely outside of
the cloud. The configuration
properties allow a connection
to be made to the remote
Oracle database.

Generic target

A component used to open

the firewall for outbound
TCP connections from a web
or enterprise application to a
specified host and port.

Database (DB2)

A database (DB2) component v JNDI name of the data

that represents a
source
pattern-deployed database
v Resource references of the
service.
data source
v Non-transactional data
source
v Minimum connections
v Maximum connections
v Connection timeout

Existing Database (DB2)

560

IBM Cloud Orchestrator 2.4.0.2: User's Guide

An existing DB2 database

v JNDI name of the data
component represents a
source
connection to a remote DB2
v Resource references of the
database instance running
data source
remotely outside of the
v
Non-transactional data
cloud. The configuration
source
properties allow a connection
to be made to the remote
DB2 database.

Table 64. Outgoing connectable components (continued)

Component name

Description

Connection

Existing Database (Informix)

An existing Informix
database component
represents a connection to a
remote Informix database
instance running remotely
outside of the cloud. The
configuration properties
allow a connection to be
made to the remote Informix
database.

v JNDI name of the data

source

Existing CICS Transaction

Gateway (TG)

v Resource references of the

data source
v Non-transactional data
source

An existing CICS TG
v JNDI name of the CICS
component represents an
TG resource
existing connection to a
CICSTG instance running
remotely outside of the
cloud. The configuration
properties allow a connection
to be made to the CICS TG.

Existing User Registry (Tivoli An existing user registry

Directory Server)
(Tivoli Directory Server)
cloud component represents
an existing Lightweight
Directory Access Protocol
(LDAP) service that can be
deployed by itself or
attached to a web application
component or an enterprise
application component. The
LDAP service provides a
user registry for
container-managed security.
Existing User Registry
(Microsoft Active Directory)

An existing user registry

(LDAP) cloud component
represents an existing LDAP
service that can be attached
to a web application
component or an enterprise
application component. The
LDAP service provides a
user registry for
container-managed security.

User Registry (Tivoli

Directory Server)

A user registry (Tivoli

Directory Server) cloud
component represents a
pattern-deployed LDAP
service that can be deployed
by itself or attached to a web
application component or an
enterprise application
component. The LDAP
service provides a user
registry for
container-managed security.

Existing OSGi Bundle

Repository

The URL of an existing OSGi

bundle repository.

v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping

Chapter 7. Managing and deploying virtual patterns

561

Table 64. Outgoing connectable components (continued)

Component name

Description

Connection

Existing Queue (WebSphere

MQ)

A message queue on an
v JNDI name
external WebSphere MQ
v Resource environment
messaging service through
references
which messages are sent and
v Message destination
received.
references

Attention: You can upload an .eba file to replace an OSGi application in the
Virtual Application Console, but you cannot rename the archive as a part of the
update.
To make a connection between a component and the OSGi application, hover over
the blue circle on the OSGi application component part on the canvas. When the
blue circle turns yellow, draw a connection between the OSGi application
repository and component.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing OSGi application component, select the OSGi application
component part on the Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new OSGi application component to a virtual application pattern,
click the OSGi Application component listed under the OSGi Components
and drag the icon to the Pattern Builder canvas. The properties panel for the
component displays to the right of the Pattern Builder palette. For more details
on the properties panel settings, view the help by selecting the help icon on the
properties panel.
6. You can also view the OSGi application component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select was/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.

562

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Transaction processing components:

There are several transaction processing components to choose from when building
a virtual application pattern.
About this task
v Existing CICS Transaction Gateway
v Existing IMS TM on page 565
Existing CICS Transaction Gateway:
An existing CICS Transaction Gateway (TG) component represents a connection to
an existing CICS TG instance running remotely outside of the cloud. The
configuration properties allow a connection to be made to the CICS TG.
Before you begin
You must install a CICS TG resource adapter on IBM Cloud Orchestrator to be able
to connect and use a CICS TG from within your cloud environment. See the topic,
Installing a CICS resource adapter.
The following are attributes for the OSGi application component:
v Connection URL: Specifies the connection URL of the existing CICS TG. This
attribute is required.
v Port Number: Specifies the port number of the existing CICS TG.
v CICS Server Name: Specifies the name of the CICS server to connect to.
v CICS user ID: Specifies the CICS user ID to be used if no other security
credentials are available.
v Password: Specifies the password that is associated with the CICS user ID to be
used.
v SSL Keyring: Specifies the Secure Socket Layers (SSL) keyring for securing a
connection to an existing CICS TG, for example, a Java keystore file. Click
Browse to search for the SSL keyring file on your system.
v SSL Keyring Password: Specifies the password for the SSL keyring.
v Applid: Specifies the APPLID for applications using this connection.
v Applid Qualifier: Specifies the APPLID qualifier for applications using this
connection.
v Tran Name: Specifies the transaction identifier for the mirror transaction placed
in EIBTRNID by CICS.
v TPN Name: Specifies the transaction identifier of the CICS mirror transaction.
v Enable trace: Specifies the if a trace is enabled for the existing CICS TG.
Connections
Table 65. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

component represents an
execution service for Java
Platform, Enterprise Edition
(Java EE) web applications
(WAR files).

v JNDI Name of the JCA

Connection Factory
v Maximum number of
connections to the CICS
Transaction Gateway

Chapter 7. Managing and deploying virtual patterns

563

Table 65. Incoming connectable components (continued)

Component name

Description

Enterprise application
(WebSphere Application
Server)

An enterprise application
v JNDI Name of the JCA
(WebSphere Application
Connection Factory
Server) cloud component
v Maximum number of
represents an execution
connections to the CICS
service for Java EE enterprise
Transaction Gateway
applications (EAR files).

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

Connection properties

v JNDI Name of the JCA

Connection Factory
v Maximum number of
connections to the CICS
Transaction Gateway

About this task

The CICS TG component represents a connection to an instance of CICS TG. The
component can be configured to create a connection to your CICS TG installation.
When you click the CICS TG component on the Pattern Builder canvas, a
properties panel is displayed.
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To add a new transaction processing component to a virtual application
pattern, click the Existing CICS Transaction Gateway component listed under
the Transaction Processing Components and drag the icon to the Pattern
Builder canvas. The properties panel for the transaction processing component
displays to the right of the Pattern Builder palette. For more details on the
properties panel settings, view the help by selecting the help icon on the
properties panel.
5. To edit an existing CICS TG component, select the Existing CICS Transaction
Gateway component part on the Pattern Builder canvas. The properties panel
displays.
You must specify the connection URL that the resource adapter uses to
communicate with CICS TG in the form protocol://address, and specify the
port number for which CICS TG is listening. The other fields in the properties
panel are optional. If you have configured SSL on CICS TG you must also enter
the name of the SSL keyring file and the SSL keyring password that you have
configured. Enter the full path name to the SSL keyring file in the SSL keyring
field, for example, /mykeys/jsse/keystore.jks.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
6. You can also view the transaction processing component properties by viewing
the plug-in information. Click PATTERNS > Deployer Configuration > System

564

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Plug-ins. Select wasctg/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Installing the CICS resource adapter:
Before you can use the CICS Transaction Gateway (CICS TG) in the IBM Cloud
Orchestrator, you must install a CICS TG resource adapter.
Before you begin
You can use the ECI adapter, cicseci.rar, or the ECI adapter with two-phase
commit support, cicseciXA.rar. IBM Cloud Orchestrator does not provide EPI
support. The resource adapters are specific to your release of CICS TG and the one
you use depends on the platform that you are using and whether you require
two-phase or single-phase commit. For further details about CICS TG resource
adapters, see Using the ECI resource adapters.
About this task
To install a CICS TG resource adapter, log on to IBM Cloud Orchestrator as an
administrator. Upload the CICS TG resource adapter for your CICS TG installation.
You can now use, and configure a CICS TG component.
Procedure
1. Click PATTERNS > Deployer Configuration > System Plug-ins. A
configuration dialog box displays.
2. Browse for the resource adapter.
3. Click OK.
Results
You have uploaded a new resource adapter.
What to do next
Add the CICS TG component to a virtual application pattern.
Existing IMS TM:
An existing Information Management Systems Transaction Manager (IMS TM)
component provides an enterprise or web application that is running on
WebSphere Application Server to connect to and submit transactions to an existing
IMS system running remotely outside of the cloud.
Before you begin
The configuration properties allow a connection to be made to the IMS TM system.
The following are the required properties:
v Resource Adapter: Specifies the file path name of the IMS TM resource adapter
(.rar file).
Chapter 7. Managing and deploying virtual patterns

565

v Server host name or IP Address: Specifies the host name or IP address of IMS
Connect. IMS Connect is the TCP/IP listener component of IMS.
v Port number: Specifies the TCP/IP port used by the target IMS Connect.
v Datastore name: Specifies the name of the target IMS system. This name must
match the ID parameter of the datastore statement that is specified in the IMS
Connect configuration member.
The following are optional properties:
v User name: Specifies the security authorization facility (SAF) user name that is
used for connections created by the connection factory.
v Password: Specifies the password associated with the user name property
v CM0Dedicated: If checked (indicates True), dedicated persistent socket
connections are generated. If cleared (indicates False), shareable persistent socket
connections are generated. The default is False.
v SSL Enabled: Check to use SSL connection to IMS TM. If using SSL then the
following parameters are required:
SSL Encryption Type: Specifies the encryption type: Strong or weak. This is
related to the strength of the ciphers, that is, the key length. By default, the
encryption type is set to weak.
SSL Keystore Name: Specifies the full file path name of the keystore. Private
keys and their associated public keys certificates are stored in
password-protected databases called keystores. An example of a keystore
name is c:\keystore\MyKeystore.ks.
SSL Keystore Password: Specifies the password for the keystore.
SSL TrustStore Name: Specifies the full file path name of the truststore. A
truststore file is a key database file that contains public keys or certificates.
SSL TrustStore Password: Specifies the password for the truststore.
Trace Level: Specifies the level of information that is traced. Here are the
possible values:
- 0: No tracing or logging occurs
- 1: Only errors and exceptions are logged (default)
- 2: Errors and exceptions plus the entry and exit of important methods are
logged
- 3: Errors and exceptions, the entry and exit of important methods, and the
contents of buffers sent to and received from IMS Connect are logged.
Connections
Table 66. Incoming connectable components
Component name

Description

Connection properties

Web application (WebSphere

Application Server)

A web application cloud

v JNDI Name of the JCA
component represents an
Connection Factory, or
execution service for Java EE
v Resource references
web applications (WAR files).
mapping
v Maximum number of
connections to IMS TM
v Connection timeout

566

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 66. Incoming connectable components (continued)

Component name

Description

Connection properties

Enterprise application
(WebSphere Application
Server)

An enterprise application
v JNDI Name of the JCA
(WebSphere Application
Connection Factory, or
Server) cloud component
v Resource references
represents an execution
mapping
service for Java EE enterprise
v
Maximum number of
applications (EAR files).
connections to IMS TM
v Connection timeout

OSGi application (WebSphere OSGi application on

Application Server)
WebSphere Application
Server

v JNDI Name of the JCA

Connection Factory, or
v Resource references
mapping
v Maximum number of
connections to IMS TM
v Connection timeout

About this task

The IMS TMRA component represents a connection to an instance of IMS TMRA.
The component can be configured to create a connection to your IMS TM
installation. When you click the IMS TMRA component on the Pattern Builder
canvas, a properties panel is displayed. You can view, edit, or add this virtual
application component in the user interface as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To add a new transaction processing component to a virtual application
pattern, click the Existing IMS TM component listed under the Transaction
Processing Components and drag the icon to the Pattern Builder canvas. The
properties panel for the transaction processing component displays to the right
of the Pattern Builder palette. For more details on the properties panel settings,
view the help by selecting the help icon on the properties panel.
5. To edit an existing web application component, select the Existing IMS TM
component part on the Pattern Builder canvas. The properties panel displays.
You must specify the resource adapter used to communicate with IMS TM, the
host name or IP address of the IMS Connect component of IMS TM, the port
number on which IMS Connect is listening and the datastore name of IMS as
specified in the IMS Connect Configuration member. The other fields in the
properties panel are optional. For more details on the properties panel settings,
see the properties descriptions or view the help by selecting the help icon on
the properties panel.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
6. You can also view the transaction processing component properties by viewing
the plug-in information. Click PATTERNS > Deployer Configuration > System

Chapter 7. Managing and deploying virtual patterns

567

Plug-ins. Select imstmra/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Other components:
There are several other components to choose from when building a virtual
application pattern.
About this task
v Generic target
v Debug on page 609
Generic target:
A generic target component is used to open the firewall for outbound TCP
connections from a web or enterprise application to a specified host and port.
Before you begin
The following are the attributes for a generic target component:
v Server (IP or IP/netmask): Specifies the target server. This attribute is required.
v Port: Specifies the destination port on the target server. This attribute is required.
Connections
Table 67. Incoming connectable components
Component name

Description

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java
Platform, Enterprise Edition (Java EE) web
applications (WAR files).

Enterprise application (WebSphere

Application Server)

An enterprise application (WebSphere

Application Server) cloud component
represents an execution service for Java EE
enterprise applications (EAR files).

OSGi application (WebSphere Application

Server)

OSGi application on WebSphere Application

Server.

To make a connection between an application component and the generic target

component, hover over the blue circle on the Informix remote database component
part on the canvas. When the blue circle turns yellow, draw a connection between
the generic target component and the application component.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:

568

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing generic target component, select the Generic target
component part on the Pattern Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new generic target component to a virtual application pattern, click
the Generic target component listed under Other Components and drag the
icon to the Pattern Builder canvas. The properties panel for the component
displays to the right of the Pattern Builder palette. For more details on these
the properties panel settings, view the help by selecting the help icon on the
properties panel.
6. You can also view the generic target component properties by viewing the
plug-in information. Click PATTERNS > Deployer Configuration > System
Plug-ins. Select connect/x.x.x.x from the System Plug-ins palette where x.x.x.x
corresponds to the version numbers. The component plug-in configuration
information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.
Policies:
There are several policies to choose from when building a virtual application
pattern.
About this task
v Scaling policy
v Routing policy on page 571
v Log policy on page 572
v JVM policy on page 573
Scaling policy:
Scaling is a Pattern Builder runtime capability to automatically scale your
application platform as the load changes. A scaling policy component defines this
capability and the conditions under which scaling activities are performed for your
application.
Before you begin
The following are the attributes for a scaling policy:
v Enable session caching: Specifies whether to use the session caching function in
your application.
v Scaling Type: Specifies the scaling type used. You can select Static,CPU Based,
Response Time Based, or Web to DB. Depending on the selection, zero or more of
the other attributes are valid.

Chapter 7. Managing and deploying virtual patterns

569

v Number of instances: Specifies the number of cluster members that are hosting
the web application. The default value is 2. Acceptable value range is 2 through
10. This attribute is required.
v Instance number range of scaling in and out: Specifies the scaling range for
instance members that are hosting the web application. Acceptable value range
is 1 through 50. This attribute is required.
v Minimum time (in seconds) to trigger add or remove: Specifies the time
duration condition to start scaling activity. The default value is 120 seconds.
Acceptable value range is 30 through 1800. This attribute is required.
v Scaling in and out when CPU usage is out of threshold range (in percentage):
Specifies the processor threshold condition to start scaling activity. When the
average processor utilization of your application platform is out of this threshold
range, your platform is scaled in or out. The default value is 20 - 80%.
Acceptable values range 0 - 100%.
v Scaling in and out when web response time is out of threshold range (in
milliseconds): Specifies the web application response time condition to start
scaling activity. When the web application response time is out of this threshold
range, your platform is scaled in or out. The acceptable values range from 0
-1000 ms.
v JDBC connections wait time is out of the threshold range (in milliseconds):
Specifies the JDBC connection wait state to start scaling activity. When the JDBC
connections wait time is out of this threshold range, your platform is scaled in
or out. The acceptable values range from 0 -10000 ms.
v JDBC connection pools usage is out of the threshold range (in percentage):
Specifies JDBC connection pool usage to start scaling activity. When the JDBC
connection usage is out of this threshold range, your platform is scaled in or out.
The acceptable values range 0 - 100%.
Note: Due to OpenStack limitations, vertical scaling (increasing memory and CPU
on running systems without stopping the service) is not supported by IBM Cloud
Orchestrator. Only horizontal scaling (increasing the number of virtual machines to
balance the workload) is supported when required by the scaling policy.
Connections
Table 68. Outgoing connectable components
Component name

Description

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java
Platform, Enterprise Edition (Java EE) web
applications (WAR files).

Enterprise application (WebSphere

Application Server)

An enterprise application (WebSphere

Application Server) cloud component
represents an execution service for Java EE
enterprise applications (EAR files).

OSGi application (WebSphere Application

Server)

OSGi application on WebSphere Application

Server.

About this task

You can view, edit, or add a scaling policy in the user interface as follows:

570

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing scaling policy, select the Scaling Policy part on the Pattern
Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new scaling policy to a virtual application pattern, you can:
v Click the Add a policy icon located in the application component part on the
canvas. Select Scaling Policy from the list of policies. The scaling policy
displays as a part in your application component part.
or
v Click the Add policy for application icon on the upper left side of the
canvas. Select the Scaling Policy from the list of policies. The scaling policy
displays on the Pattern Builder canvas. The policy is applied to all applicable
components in the canvas.
Results
You have edited a current component, edited an existing policy, or added one.
Routing policy:
You can apply a routing policy to the application component parts of your virtual
application pattern.
Before you begin
The following are the attributes for a routing policy:
v Virtual hostname: Specifies the name of the virtual host for the routing policy.
This attribute is required.
v HTTP: Specifies support for HTTP schema with a routing policy.
v HTTPS: Specifies support for HTTPS schema with a routing policy.
Connections
Table 69. Outgoing connectable components
Component name

Description

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java EE
web applications (WAR files).

Enterprise application (WebSphere

Application Server)

An enterprise application (WebSphere

Application Server) cloud component
represents an execution service for Java EE
enterprise applications (EAR files).

OSGi application (WebSphere Application

Server)

OSGi application on WebSphere Application

Server.

Chapter 7. Managing and deploying virtual patterns

571

About this task

You can view, edit, or add a routing policy in the user interface as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing routing policy, select the Routing Policy part on the Pattern
Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new routing policy to a virtual application pattern, you can:
v Click the Add a policy icon located in the application component part on the
canvas. Select Routing Policy from the list of policies. The routing policy
displays as a part in your application component part.
OR
v Click the Add policy for application icon on the top left side of the canvas.
Select the Routing Policy from the list of policies. The routing policy
displays on the Pattern Builder canvas. The policy is applied to all applicable
components in the canvas.
Results
You have edited a current component, edited an existing policy, or added one.
Log policy:
A log policy can be added to your application component part to specify
configurations for log records.
Before you begin
The following are the attributes for a log policy:
v Log detail levels: Specifies the usage of log levels to control which events are
processed by Java logging.
v Additional Log Files or Directories to Monitor: Specifies a semicolon delimited
list of directories or files to monitor. To specify that an entry is a directory, suffix
the entry with a slash, for example, /var/log/myApplication/, or prefix it with
the string, such as, dir:/var/log/myApplication. You can use an asterisk
wildcard in the file-specification only, for example, /var/log/myApplication/
*.log. Using the wild card like the following, /var/log/*/my.log, is invalid. Any
directory specified is visible in the Log Viewer.
Connections
Table 70. Outgoing connectable components

572

Component name

Description

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java
Platform, Enterprise Edition (Java EE) web
applications (WAR files).

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 70. Outgoing connectable components (continued)

Component name

Description

Enterprise application (WebSphere

Application Server)

An enterprise application (WebSphere

Application Server) cloud component
represents an execution service for Java EE
enterprise applications (EAR files).

OSGi application (WebSphere Application

Server)

OSGi application on WebSphere Application

Server.

About this task

You can view, edit, or add a log policy in the user interface as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing log policy, select the Log Policy part on the Pattern Builder
canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new log policy to a virtual application pattern, you can:
v Click the Add policy for application icon located in the application
component part on the canvas. Log Policy from the list of policies. The log
policy displays as a part in your application component part.
or
v Click the Add policy for application icon on the upper left side of the
canvas. Select the Log Policy from the list of policies. The log policy displays
on the Pattern Builder canvas. The policy is applied to all applicable
components in the canvas.
Results
You have edited a current component, edited an existing policy, or added one.
JVM policy:
A Java virtual machine (JVM) policy controls the underlying JVM. You can attach
the JVM policy to debug WebSphere Application Server processes using an
integrated development environment (IDE) like IBM Rational Application
Developer for WebSphere.
Before you begin
The following are the attributes for a JVM policy:
v Minimum heap size: Specifies the minimum heap size of the JVM specified size
in megabytes (MB).
v Maximum heap size: Specifies the maximum heap size of the JVM specified size
in megabytes (MB).
v Enable debug: Specifies if the JVM is in debug mode.
Chapter 7. Managing and deploying virtual patterns

573

v Debug port: Specifies the port that the JVM listens on for remote connections.
v Client (IP or IP/netmask): The IP address of the host that is being used to
debug.
v Client: Specifies an optional address of the debug client. This setting is used to
restrict source access to the debug port. Value is an IP address, for example,
1.2.3.4; or IP/netmask, for example, 1.2.0.0/255.255.0.0, which matches anything
in the 1.2. network.
v Enable verbose garbage collection: Specifies if the JVM has garbage collection
enabled.
v Generic JVM arguments:
v Bit level: Specifies if the bit level is set to 32 bit or 64 bit.
Connections
Table 71. Outgoing connectable components
Component name

Description

Web application (WebSphere Application

Server)

A web application cloud component

represents an execution service for Java EE
web applications (WAR files).

Enterprise application (WebSphere

Application Server)

An enterprise application (WebSphere

Application Server) cloud component
represents an execution service for Java EE
enterprise applications (EAR files).

OSGi application (WebSphere Application

Server)

OSGi application on WebSphere Application

Server.

About this task

When you enable debugging, the JVM is started in the debug mode and is
listening on the specified port. A debugger on any client machine can attach to the
JVM by default. You can specify a client IP address or IP/netmask to restrict access
to the JVM. A client IP address, such as 10.2.3.5, allows a specific client machine to
debug. An IP/netmask, such as 10.2.3.5/255.255.0.0, allows any machine on the
10.2 network to attach to the JVM.
You can view, edit, or add a JVM policy in the user interface as follows:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To edit an existing JVM policy, select the JVM Policy part on the Pattern
Builder canvas. The properties panel displays.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
5. To add a new JVM policy to a virtual application pattern, you can:
v Click the Add policy for application icon located in the application
component part on the canvas. JVM Policy from the list of policies. The JVM
policy displays as a part in your application component part.
or

574

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Click the Add policy for application icon on the upper left side of the
canvas. Select the JVM Policy from the list of policies. The JVM policy
displays on the Pattern Builder canvas. You can connect the policy to an
application component part by hovering over the blue circle on the
application component part. When the blue circle turns yellow, draw a
connection between the application component and the policy.
Results
You have edited a current component, edited an existing policy, or added one.
What to do next
For more detailed information about using Rational Application Developer for
WebSphere, see Debugging applications in the WebSphere Application Server
Information Center.
You can optionally use the IBM Monitoring and Diagnostic Tools for Java - Health
Center (Health Center) to assess the current status of a running Java application.
Health Center continuous monitoring provides information that helps you to
identify and resolve problems with applications.
In IBM Cloud Orchestrator, you can configure the IBM Monitoring and Diagnostic
Tools for Java - Health Center using the following attributes in the JVM policy:
v Enable Health Center: Specifies to start the JVM with Health Center enabled.
Health Center is not enabled by default.
v Health Center port: Specifies the port for which the Health Center agent listens
for remote connections.
v Health Center Client: Specifies the IP address of the Health Center client. This is
an optional setting.
Technical information regarding the IBM Monitoring and Diagnostic Tools for Java
- Health Center is available at the following URL:
https://www.ibm.com/developerworks/java/jdk/tools/healthcenter/

Developing plug-ins
Plug-ins define the components, links, and policies that you use in the Pattern
Builder to create virtual application patterns, or extend existing virtual application
patterns. This guide describes how to develop your own custom plug-ins. Custom
plug-ins add behavior and function that users can exploit to enhance and
customize the operation of their virtual applications.

Before you begin

Download the Plug-in Development Kit (PDK). You can also download the PDK
from the IBM Cloud Orchestrator user interface Welcome page.

About this task

Use the following steps to develop your own custom plug-ins. The plug-in can be
developed in the Eclipse tool or the integrated development environment (IDE) of
your choice.

Chapter 7. Managing and deploying virtual patterns

575

Procedure
1. Define and package plug-in artifacts.
a. Define the config.json file.
The config.json file is the only required file in a plug-in. The name,
version, and patterntypes elements are all required. The name element
specifies the name of the plug-in, and the version element defines the
version number of the plug-in. The patterntypes element specifies the
pattern types with which the plug-in is associated. The following example is
a WebSphere Application Server Community Edition plug-in that extends
the IBM Web Application Pattern type (not released with the product):
{
"name"
: "wasce",
"version" : "1.0.0.1",
"patterntypes":{
"secondary":[{ "*":"*"}]
},
"packages" : {
"WASCE" : [ {
"requires" : {
"arch"
: "x86_64",
"memory" : 512,
"disk"
: 300
},
"parts":[ {
"part" : "parts/wasce.tgz",
"parms" : {
"installDir" : "/opt/wasce"
}
} ],
"WASCE_SCRIPTS":[ {
"parts":[ {
"part":"parts/wasce.scripts.tgz"
} ]
} ]
} ]
}
}

This example defines most of the following common elements:

v patterntype element:
The value is specified as webapp.
This means that the capabilities contributed by this plug-in are available
when you create patterns from the Web Application Pattern (not released
with the product). No primary element and a secondary element of *:*
means it shows up in the Pattern Builder for all pattern types.
v requires element:
This element contains other elements that specify resource requirements
of the plug-in.
os
Specifies the operating system that the plug-in requires.
arch
Specifies the virtual machine architecture that the plug-in requires. In
the previous config.json sample code, the specified architecture is 64 bit, X86.
cpu
Specifies the minimum processing capacity that is required for each
package defined by your plug-in. The requires element specifies the

576

IBM Cloud Orchestrator 2.4.0.2: User's Guide

required attributes of the package, all parts and node-parts in it. For
cpu it represents the total required resources of each type for all parts
and node-parts in the package.
memory
Specifies the minimum memory requirement for each package defined
by your plug-in. The requires element specifies the required attributes
of the package, all parts and node-parts in it. For memory it represents
the total required resources of each type for all parts and node-parts in
the package.
disk
Specifies the minimum disk requirement for each package defined by
your plug-in. The requires element specifies the required attributes of
the package, all parts and node-parts in it. For disk it represents the
total required resources of each type for all parts and node-parts in the
package.
Note: During the provisioning process, IBM Cloud Orchestrator adds up
the minimum CPU, memory, and disk values for each package, and
provisions a virtual machine that meets the specified requirements.
v packages element:
Defines the file packages with both the part and nodepart elements. The
example plug-in provides two packages: WASCE and WASCE_SCRIPTS.
The WASCE package contains the parts/wasce.tgz part file. This archive
contains the wasce image - all the files that compose wasce. The binaries
are required to install WebSphere Application Server Community Edition,
and package it directly in the plug-in.
There are other options for specifying the required binaries. You can
define a file attribute and have administrators upload the required
binaries after loading the plug-in in IBM Cloud Orchestrator. You can also
link to a remote server that stores the required artifacts. The
WASCE_SCRIPTS package provides the life cycle scripts to install the
WASCE image to the desired location, to install the enterprise archive
(EAR) or web archive (WAR) file, and to start the server.
2. Define configurable application model components.
The web and enterprise application archive components are displayed in the
Pattern Builder. Each component is specified in the metadata.json file that is
located in the plugin/appmodel directory of the plug-in archive and plugin
development project. The following example illustrates the JSON to define the
web archive component:
[{
"id"
: "WARCE",
"label"
: "Web Application (WebSphere Application Server Community Edition)",
"description" : "A web application cloud component represents an execution service
for Java EE Web applications (WAR files).",
"type"
: "component",
"thumbnail" : "appmodel/images/WASCE.png",
"image"
: "appmodel/images/WASCE.png",
"category"
: "application",
"attributes" : [
{
"id"
: "archive",
"label"
: "WAR File",
"description" : "Specifies the web application (*.war) to be uploaded.",
"type"
: "file",
"required"
: true,

Chapter 7. Managing and deploying virtual patterns

577

"extensions"

: [ "war" ]

}
]
}]

There is a similar stanza for the enterprise archive component for its
downloadable archive.
The first type field of the listing is important. The value options for this field
are component, link or policy, and this defines the type in the application
model. The id of the component is WARCE. This can be any value as long as it is
unique.
The category refers to the tab under which this component is shown on the
palette in the Pattern Builder. The attributes array defines properties for the
component that you are defining. You can see and are able to specify values for
these properties when using this component in the Pattern Builder. Attribute
types include file, string (shown here), number, boolean, array, and range.
3. Define a template to convert the visual model into a physical model.
Plug-ins must provide the knowledge and logic for how to implement, or
realize, the deployment of the defined components. In the case of the next
example, the meaning of how to deploy an enterprise or web application
component must be specified. To do this, a single transform is provided that
translates the application model derived from what users build in the Pattern
Builder into a concrete topology.
The following example displays a Velocity template that represents a
transformation of the component into a JSON object that represents a fragment
of the overall topology document. Each component and link must have a
transform. In our plug-in, the WARCE and EARCE components share the same
transform template.
{
"vm-templates":[
{
"name"
: "${prefix}-wasce",
"packages" : [ "WASCE", "WASCE_SCRIPTS" ],
"roles"
: [
{
"plugin"
: "$provider.PluginScope",
"name"
: "WASCE",
"type"
: "WASCE",
"quorum"
: 1,
"external-uri" : [{"ENDPOINT":"http://{SERVER}:8080"}],
"parms":{
"ARCHIVE"
: "$provider.generateArtifactPath( $applicationUrl,
${attributes.archive} )"
},
"requires"
: { "memory":512, "disk":300 }
}
],
"scaling" : { "min":1, "max":1 }
}
]
}

The topology fragment is a JSON object that contains a vm-templates element,

which is an array of vm-templates. A vm-template is a virtual machine
template, and defines the parts, nodeparts, and attributes of a virtual machine
to be deployed. For this example, only a single vm-template that contains four
important elements is needed:
v name: Specifies a unique name for a deployed virtual machine.

578

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v packages: Specifies a list of parts and nodeparts that are installed on each
deployed virtual machine. The WASCE entry indicates the use of the WASCE
virtual image. The WASCE_SCRIPTS entry specifies the WASCE life cycle
scripts.
v roles: Specifies parts in a plug-in that invoke lifecycle scripts for roles. You
can have one or more roles in your plug-in, but in the sample plug-in there
is a single WASCE role. When all roles on a node go to the RUNNING state, the
node changes to the green RUNNING state.
4. Define lifecycle scripts to install, configure, and start software.
In this step, you define the lifecycle scripts for the plug-in. This process
includes writing scripts to install, configure, and start the plug-in components.
You can view the complete scripts in the downloadable archives. The following
information includes the key artifacts:
v install.py script
The install.py script copies the WASCE image from the download location
to the desired installDir folder. It also sets the installDir value in the
environment for subsequent scripts. All parts and nodeparts installed by the
IBM Cloud Orchestrator agent run as root. The chown R virtuser:virtuser
command changes file ownership of the installed contents to the desired user
and group. Finally, the install.py script makes the scripts in the WebSphere
Application Server Community Edition bin directory executable. The
following sample code is the contents of the install.py script:
installDir = maestro.parms[installDir]
maestro.trace_call(logger, [mkdir, installDir])
if not WASCE in maestro.node[parts]:
maestro.node[parts][WASCE] = {}
maestro.node[parts][WASCE][installDir] = installDir
# copy files to installDir to install WASCE
this_file = inspect.currentframe().f_code.co_filename
this_dir = os.path.dirname(this_file)
rc = maestro.trace_call(logger, cp -r %s/files/* %s % (this_dir, installDir), shell=True)
maestro.check_status(rc, wasce cp install error)
rc = maestro.trace_call(logger, [chown, -R, virtuser:virtuser, installDir])
maestro.check_status(rc, wasce chown install error)
# make shell scripts executable
rc = maestro.trace_call(logger, chmod +x %s/bin/*.sh % installDir, shell=True)
maestro.check_status(rc, wasce chmod install error)

This example shows how the script makes use of the maestro module
provided within the plug-in framework. The module provides several helper
methods that are useful during installation and elsewhere.
v wasce.scripts part and install.py script
The wasce.scripts part also contains a install.py script. This script installs
the WebSphere Application Server Community Edition life cycle scripts. The
following is an example of the install.py script in wasce.scripts:
# Prepare (chmod +x, dos2unix) and copy scripts to the agent scriptdir
maestro.install_scripts(scripts)

v configure.py script
The configure.py script in the wasce.scripts part installs the user-provided
application to WebSphere Application Server Community Edition. The script
takes advantage of the hot deploy capability of WebSphere Application
Server Community Edition and copies the application binaries to a
monitored directory. The following example includes the contents of the
configure.py script:
Chapter 7. Managing and deploying virtual patterns

579

installDir = maestro.node[parts][WASCE][installDir]
ARCHIVE = maestro.parms[ARCHIVE]
archiveBaseName = ARCHIVE.rsplit(/)[-1]
# Use hot deploy
deployDir = os.path.join(installDir, deploy)
if os.path.exists(deployDir) == False:
# Make directories
os.makedirs(deployDir)
deployFile = os.path.join(deployDir, archiveBaseName)
# Download WASCE archive file
maestro.download(ARCHIVE, deployFile)

v start.py
The start.py script in the wasce.scripts part is responsible for starting the
WebSphere Application Server Community Edition process. After starting the
process, the script updates the state of the role to RUNNING. When the
deployment is in the RUNNING state, you can access the deployed application
environment. The following example shows the use of the geronimo.sh start
command to start WebSphere Application Server Community Edition, as well
as the gsh.sh command to wait on startup:
wait_file = os.path.join(maestro.node[scriptdir], WASCE, wait-for-server.txt)
installDir = maestro.node[parts][WASCE][installDir]
rc = maestro.trace_call(logger, [su, -l, virtuser, installDir + /bin/geronimo.sh,
start])
maestro.check_status(rc, WASCE start error)
logger.info(wait for WASCE server to start)
rc = maestro.trace_call(logger, [su, -l, virtuser, installDir + /bin/gsh.sh,
source, wait_file])
maestro.check_status(rc, wait for WASCE server to start error)
maestro.role_status = RUNNING
logger.info(set WASCE role status to RUNNING)
logger.debug(Setup and start iptables)
maestro.firewall.open_tcpin(dport=1099)
maestro.firewall.open_tcpin(dport=8080)
maestro.firewall.open_tcpin(dport=8443)

There are other scripts and artifacts that make up the plug-in, but the above
provides an explanation of the most significant scripts.

What to do next
Add your custom plug-in to IBM Cloud Orchestrator where the plug-in can be
used to create or extend a virtual application.
Plug-in Development Kit:
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
IBM Cloud Orchestrator. The custom plug-ins can be added to the IBM Cloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Attention:

Download the PDK to get started.

The PDK is a zip package that includes a plug-in and pattern type build
environment, samples, and a tool to create a plug-in starter project
v docs

580

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Contains documentation for the PDK

docs/index.html Contains a list of links to the documentation in the docs
directory.
docs/PDKSampleUsersGuide.pdf
The PDK Samples User Guide. The Samples are also located in the
information center.
docs/javadoc
This directory contains Javadoc for IBM Cloud Orchestrator interfaces that the
plug-ins can invoke from the Java code.
docs/pydoc
This directory contains documentation for the maestro module used in
lifecycle Python scripts for nodeparts and parts.
v iwd-pdk-workspace
The root directory of your plugin development workspace.
Each plug-in and pattern types has its own project directory in this root
directory. These directories can be used directly from the command line or
imported into Eclipse as plug-ins.
v pdk-debug-{version}.tgz
This file is the debug plug-in that can be installed into the IBM Cloud
Orchestrator instance and used to develop and debug the plug-ins.
The debug includes features to deploy and debug a topology document, which
is a JSON object, and debug plug-in installation and lifecycle scripts on
deployed nodes. For more information, see the topic, Debug.
v pdk-unlock-{version}.tgz
The unlock plug-in enables you to delete a plug-in in use by a deployed
application, replace it with an updated version, and activate the modified
plug-in on deployed virtual machines in the application. For more information,
see the topic, Unlock.
plugin.depends tool
The plugin.depends tool is provided in the
IBMWorkloadPluginDevKit_<version>.zip file. This plug-in development tool is a
standard OSGi plug-in project. The tool includes IBM Cloud Orchestrator plug-in
libraries for development, build tools for plug-in and pattern types, and an Ant
build library, including:
v The lib folder that includes all of the Java archive (JAR) files that are required
for plug-in development.
v The lib-build folder that includes all of the libraries that are required for the
plug-in build script.
v The build/build.plugins.xml file that is the base internal build script file for
single plug-in building. The build script file of each plug-in imports this build
script file first and adds more actions, if necessary.
v The build/build.patterntypes.xml file which is a generic pattern type building
script. The build script file of each pattern type imports this build script file first
and adds more actions, if necessary.
v The create.plugin.project.xml file which is an Ant script used to create
projects for the plug-ins in your workspace.
You can use the create.plugin.project.xml file of plugin.depends to create
projects for your plug-ins. This file creates a template or a Java plug-in project.
There are two required parameters: project-name and plugin-name. Using these
Chapter 7. Managing and deploying virtual patterns

581

two parameters creates a template project. The third parameter, java.classname,

is optional. If a valid class name is given, a Java plug-in project is created. The
class name can be a simple name like MyPlugin or a package-qualified name, like
com.acme.iwd.plugin.MyPlugin.
Important: Do not add the extension,.java to the end of the Java plug-in
project, because the extension is assumed.
v The plugin-project-template that is used by the create.plugin.project.xml
Ant script to create plug-in projects.
Samples
A Samples package is included with the PDK. See the topic, Samples: Plug-in
Development, for more information.
Development plug-ins
Several plug-ins to assist with plug-in development are included in the PDK. For
more information, see Plug-ins for development on page 609.
Installing the Plug-in Development Kit:
To get started using the Plug-in Development Kit, first download and install the
kit.
Before you begin
You can download the PDK from this IBM website or download the PDK from the
IBM Cloud Orchestrator user interface Welcome page.
Attention: You must enable the PDK license before you can use the PDK. A
dialogue box displays during download to assist you with the license acceptance
process.
About this task
Use the following steps to download and install the PDK:
Procedure
1. Download the PDK from IBM Plug-in Development Kit or download the PDK
from the IBM Cloud Orchestrator user interface Welcome page.
2. Extract the .zip file into a directory. From the command line, change to that
directory and run Ant from the command line in that directory.
Important: You must accept the PDK license presented in a dialogue box to
continue and unpack the contents of the PDK.
The following files are extracted into the file directory:
v docs
Contains documentation for the PDK
docs/index.html Contains a list of links to the documentation in the docs
directory.
docs/PDKSampleUsersGuide.pdf
The PDK Samples User Guide. The Samples are also located in the
information center.

582

IBM Cloud Orchestrator 2.4.0.2: User's Guide

 docs/javadoc
This directory contains Javadoc for IBM Cloud Orchestrator interfaces that
the plug-ins can invoke from the Java code.
docs/pydoc
This directory contains documentation for the maestro module used in
lifecycle Python scripts for nodeparts and parts.
v iwd-pdk-workspace
The root directory of your plugin development workspace.
Each plug-in and pattern types has its own project directory in this root
directory. These directories can be used directly from the command line or
imported into Eclipse as plug-ins.
v pdk-debug-{version}.tgz
This file is the debug plug-in that can be installed into the IBM Cloud
Orchestrator instance and used to develop and debug the plug-ins.
The debug includes features to deploy and debug a topology document,
which is a JSON object, and debug plug-in installation and lifecycle scripts
on deployed nodes. For more information, see the topic, Debug.
v pdk-unlock-{version}.tgz
The unlock plug-in enables you to delete a plug-in in use by a deployed
application, replace it with an updated version, and activate the modified
plug-in on deployed virtual machines in the application. For more
information, see the topic, Unlock.
Results
The PDK is downloaded and installed. Now you must complete the task of
Setting up the plug-in development environment.
Setting up the plug-in development environment:
Set up the environment to develop custom plug-ins that are used in IBM Cloud
Orchestrator
Before you begin
The following products are required before setting up the environment:
v Eclipse V3.6.2, 32-bit. The Java Platform, Enterprise Edition (Java EE) version is
recommended.
Eclipse is not required, but if you use it, use this version.
If you use Eclipse, you can use the Ant that comes with it. Do not install Ant
separately. Ant is located in the Eclipse installation directory at
eclipse/plugins/org.apache.ant_1.*.

v Java Standard Edition (SE) 6, 32-bit

v Apache Ant, 1.7 or later
About this task
To set up your environment, complete the following steps:
Procedure
1. From the command line type cd iwd-pdk-workspace/plugin.depends.
Chapter 7. Managing and deploying virtual patterns

583

2. In the plugin.depends project, run the build.xml Ant script. To run the Ant
script, right-click on the file and select Run As > Ant Build. OR, type ant in
the command line. This command builds all the plug-ins in the workspace.
3. Access the patterntypetest.basic project and run the build.patterntype.xml
script. Type ant -f build.patterntype.xml. This command builds the pattern
type.
4. Refresh the patterntypetest.basic project. A folder named, export, displays.
5. Navigate to the root of the export folder. The .tgz pattern type binary file is
located here. The export/archive directory contains the built pattern type that
is ready for installation into IBM Cloud Orchestrator.
6. Import the pattern type .tgz and use the plug-in from the IBM Cloud
Orchestrator catalog.
Plug-in development guide:
If you are developing custom plug-ins, this topic provides more details about
various aspects of plug-ins in the order encountered during a typical development
effort.
The following list is the high-level sections for this plug-in development reference
guide:
v Kernel services
Transformers: TopologyProvider services
Enhance template transforms with Java code
Plug-in components available as OSGi Declarative Services
v Deployment on page 590
Activation
Nodeparts

Parts
Roles
Set repeatable task
Recovery: Reboot or replace?

Virtual Application Console

v Other reference on page 605
v Application model and topology document examples on page 605
Kernel services
Transformers: TopologyProvider services
TopologyProvider implementations are plug-in-specific services for transforming
component, links, and policies from an application model into an unresolved
topology.
The transform step is a multi-step operation. First, the components are
transformed. Attached policies are integrated into the component as extended
attributes. Each component transformer takes the associated object from the
application model as input, and returns a corresponding fragment of the topology
document. The topology document and its fragments are JSON object documents.
Links are transformed after the components. Links modify the
component-generated topology documents, for example, parts and depends objects

584

IBM Cloud Orchestrator 2.4.0.2: User's Guide

are added to the source roles. Each link transformer receives the topology
fragments as input that is generated by the link source and target components.
There are two types of transformers:
v Template-based implementations
Most transforms can be described using a template of the intended JSON
document (topology fragment for components; depends objects for links). IBM
Cloud Orchestrator embeds Apache Velocity 1.6.2 as a template engine.
Template-based implementations include:
Component document
The component name must match the "id" of the component, link, and policy
that is defined in the plug-in appmodel/metadata.json file. Template files are
specified as component properties, where the value is a path relative to the
plug-in root. For example, the transformer for the sample starget component
and link looks like the following:
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="starget">
<implementation class="com.ibm.maestro.model.transform.template.TemplateTransformer"/>
<service>
<provide interface="com.ibm.maestro.model.transform.TopologyProvider"/>
</service>
<property name="component.template" type="String"
value="templates/starget_component.vm"/>
<property name="link.template" type="String"
value="templates/starget_link.vm"/>
</src:component>

Implementation
The sample starget_component.vm illustrates component transformation as
follows:
{
"vm-templates": [
{
"scaling":{
"min": 1,
"max": 1,
},
"name": "${prefix}-starget",
"roles": [
{
parms: {
"st1": "$attributes.st1"
},
"type": "starget",
"name": "starget"
}
]
}
]
}

The sample starget_link.vm illustrates link transformation as follows:

## Link templates render the depends objects to be added to the source role.
## sourceRole is required to locate the source of the link.
## Value is the type of the source role.
#set( $sourceRole = "ssource" )
## sourcePackages is an optional array. Values in the array are added to the packages
## of the vm-template that is hosting the source role.
#set( $sourcePackages = ["pkg2"] )
## Obtain a tuple related to the matching target role:
## that holds the target role; target.role == role
## String argument is the type of the target role.

target.template == vm-template

Chapter 7. Managing and deploying virtual patterns

585

#set( $target = $provider.getMatchedRole($targetFragment, "starget") )

## Validate target. If not found, throw HttpException
#if( $target == $null )
$provider.throwHttpException(Target Role starget not found.)
#end
[
{
"role" : "${target.template.name}.${target.role.name}",
"type" : "type",
parms: {
"sl1": "$attributes.sl1"
}
}
]

The sample ssource_component.vm illustrates a more complex component

transformation. The #if_value is a Velocimacro for conditional rendering of
formatted strings: If $map contains a non-empty value for $key, then
$format_str is evaluated and the value is available as $value.
{

##
##
##
##
##
##

"vm-templates": [
{
"scaling":{
"min": 1,
"max": 1
},
"name": "${prefix}-ssource",
"roles": [
{
parms: {
Handling optional attributes:
macro syntax: #macro( if_value $map $key $format_str )
String value:
#if_value( $attributes, "ss_s", "ss_s": "$value", )
Number value:
#if_value( $attributes, "ss_n", "ss_n": $value, )
Boolean value:
#if_value( $attributes, "ss_b", "ss_b": $value, )
Missing value -- will not render:
#if_value( $attributes, "not_defined", "not_defined": "$value", )

## For artifacts, Inlet may send app model with absolute URLs for artifacts; other request
## paths might invoke with relative URLs. So use provider.generateArtifactPath(), which
## invokes URI.resolve() that handles both cases.
## Handling required attributes; throws an exception if the attribute is
## null/empty/not defined
"ss_f": "$provider.generateArtifactPath( $applicationUrl, ${attributes.ss_s} )",
## Handling range value (ss3)
"ss_r_min":"$attributes.ss_r.get(0)",
"ss_r_max":"$attributes.ss_r.get(1)",
## Handling policies: spolicy is defined; not_policy is not
#set( $spattrs = $provider.getPolicyAttributes($component, "spolicy") )
#if_value( $spattrs, "sp1", "sp1": "$value", )
#if_value( $spattrs, "not_defined", "not_defined": "$value", )
#set( $npattrs = $provider.getPolicyAttributes($component, "no_policy") )
#if_value( $npattrs, "np1", "np1": "$value", )
## Handling required config parms; throws an exception if the parm is
## null/empty/not defined
"cp1": "$config.cp1"
},
"type": "ssource",
"name": "ssource"
}

586

IBM Cloud Orchestrator 2.4.0.2: User's Guide

]
}
]
}

Other available template features

Using static Java static classes
You can insert Java classes into the context with the
$provider.getClassForName method. This feature is useful when static
methods are used on these classes in your template. For example:
#set( $Math = $provider.getClassForName(java.lang.Math) )
"ss_r_math_max":$Math.max($attributes.ss_r.get(0), $attributes.ss_r.get(1)),
ss_r

is a range value, as defined in the plug-in appmodel/metadata.json file, which

is a list with two long integer values. The lower range value is the first value
in the list, with index 0. The upper range is the second value, with index 1.
The previous example returns the upper range value, but is intended to show
the usage of the java.lang.Math.max static method.
v Java implementations
For cases where templates are not sufficient, Java implementations can be used.
Java implementations can generate the JSON documents with the included JSON
APIs (com.ibm.json.java.*) or by modifying templates. Another option is to use
templates and enhance them with Java functions. See the section, Enhancing
template transforms with Java code, for details. This alternative is preferred.
Component document
The component name must match the ID of the component, link, and policy
that are defined in the plug-in appmodel/metadata.json file. For example, the
transformer for the web archive (WAR) component is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="WAR">
<implementation class="com.ibm.maestro.model.transform.was.WARTransformer"/>
<service>
<provide interface="com.ibm.maestro.model.transform.TopologyProvider"/>
</service>
</src:component>

Implementation
Implementations extend com.ibm.maestro.model.transform.TopologyProvider
and can implement component and link transformations by overriding the
corresponding methods:
public JSONObject transformComponent(
String vmTemplateNamePrefix,
String applicationUrl,
JSONObject applicationComponent,
Transformer transformer)
throws Exception {
return new JSONObject();
}
public void transformLink(
JSONObject sourceFragment,
JSONObject targetFragment,
String applicationUrl,
JSONObject applicationLink,
Transformer transformer)
throws Exception {
}

- Invoking templates
Chapter 7. Managing and deploying virtual patterns

587

Java implementations can start templates using the following methods of

TopologyProvider:
public static JSONArtifact renderTemplateToJSON(Bundle b, String template,
String logTag, Context context) throws HttpException;
public static String renderTemplate(Bundle b, String template, String logTag,
Context context) throws HttpException;

For example, the WebSphere Application Server transformer starts a

template to generate the topology fragment for a WebSphere Application
Server instance as follows:
protected void activate(ComponentContext context){
_bundle = context.getBundleContext().getBundle();
}
@Override
public JSONObject transformComponent(String prefix, String applicationUrl,
JSONObject component, Transformer transformer) throws Exception {
JSONObject topology;
JSONObject scalingPolicy = getPolicy(component, "ScalingPolicyofWAS");
String vmTemplateName = prefix + "-was";
if (scalingPolicy == null) {
VelocityContext context = new VelocityContext();
context.put(TemplateTransformer.PREFIX, prefix);
context.put(TemplateTransformer.APPLICATION_URL, applicationUrl);
// Value ends with a slash.
context.put(TemplateTransformer.COMPONENT, component);
JSONObject attributes = (JSONObject) component.get("attributes");
context.put(TemplateTransformer.ATTRIBUTES, new RequiredMap(attributes));
context.put(TemplateTransformer.CONFIG, new RequiredMap(getConfigParms()));
context.put(TemplateTransformer.PROVIDER, this);
String logTag = "WAS:templates/SingleWAS.vm";
topology = (JSONObject) renderTemplateToJSON(_bundle, "templates/SingleWAS.vm",
logTag, context);

Enhancing template transforms with Java code

Template transforms are recommended. If you need Java code, do as much as you
can with the template, and then add Java methods that you start from your
template as follows:
1. Create your Java class and have it extend TemplateTransformer.
2. Add your Java methods. The public methods can be started from your template
by using $provider.myMethod(). You can pass parameters into the Java
methods.
3. Update your OSGi component document to set the implementation class to
your new Java class, not TemplateTransformer. There are two methods for
updating the velocity context:
v The velocity context is available in the velocity context, therefore you can
pass it into a Java method using $context.
v Implement the protected VelocityContext createContext(String applicationUrl,
JSONObject component) method. In your method, call
super.createContext(applicationUrl, component). The returned
VelocityContext is the velocity context, to which you can add your custom
objects.
Important: Be careful not to overwrite any existing keys.

588

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The following code example illustrates enhancing the templates:

osgi.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/src/v.1.1.0" name="WASDB2">
<implementation class="com.ibm.maestro.model.transform.wasdb2.WASDB2LinkTransform"/>
<service>
<provide interface="com.ibm.maestro.model.transform.TopologyProvider"/>
</service>
<property name="link.template" type="String" value="templates/wasdb2_link.vm"/>
</scr:component>

Java file:
package com.ibm.maestro.model.transform.wasdb2;
import com.ibm.maestro.common.http.HttpException;
import com.ibm.maestro.model.transform.template.RequiredMap;
import com.ibm.maestro.model.transform.template.TemplateTransformer;
public class WASDB2LinkTransform extends TemplateTransformer {
public static JndiNameResourceRefs getJndiNameAndResourceRefs(RequiredMap attributes)
throws HttpException {
return JndiNameResourceRefs.getJndiNameAndResourceRefs(attributes);
}
}

Plug-in components available as OSGi Declarative Services

IBM Cloud Orchestrator provides limited support for OSGi services within
plug-ins. Specifically, plug-ins can provide implementations of specific IBM Cloud
Orchestrator service interfaces such as:
v TopologyProvider
Review the Javadoc for more information.
Attention: Javadoc is included with the pdk.zip. Extract the javadoc.zip file
and expand the file to get the Javadoc.
v TopologyProcessor
Review the Javadoc for more information.
v ServiceProvisioner
Review the Javadoc for more information.
v PostProvisioner
package com.ibm.maestro.iaas;
import org.apache.wink.client.RestClient;
import com.ibm.json.java.JSONObject;
public interface PostProvisioner {
public void provisioned(final JSONObject topology, final
JSONObject deployment, RestClient restClient);
}

Review the Javadoc for more information.

v AppBindingsService
v RegistryProvider
Review the Javadoc for more information.
Chapter 7. Managing and deploying virtual patterns

589

Kernel services manage multiple versions of these services according to the

plug-ins associated with the application model. However, version management
does not apply to other services, so errors might occur if a plug-in exports another
service implementation.
Deployment
Activation
Each image contains a startup script that is started after the virtual machine starts.
This script is the hook point behaviors on a virtual machine, therefore,
understanding the sequence of operations is helpful
Each virtual machine is assigned a unique name within the deployment. The name
is set as an environment variable named SERVER_NAME. The value is formed by
appending an ordinal to the corresponding vm-template name, for example,
application-was.1, application-was.2. Activation proceeds as follows:
1. Get this virtual machine vm-template from the topology document, for
example, if SERVER_NAME == application-was.1, then get the vm-template
named application-was.
2. For each nodepart in the vm-template:
a. Download the nodepart .tgz file and extract into the {nodepkgs_root}
directory.
b. Invoke{nodepkgs_root}/setup/setup.py, if the script exists. Associated
parms from the topology document are available as maestro.parms.
c. Delete {nodepkgs_root}/setup/.
3. Run the installation scripts ({nodepkgs_root}/common/install/*.sh|.py) in
ascending order.
4. Run the start scripts ({nodepkgs_root}/common/start/*.sh|.py) in ascending
order.
In Step 2, nodeparts should not rely on the order of installation; that is, the
setup/setup.py script should rely on contents of that nodepart only. One exception
is the maestro module. The module initialization script is in place, so that the
setup.py script can use the maestro HTTP client utility methods, for example,
maestro.download(), and maestro.parms, to obtain configuration parameters.
Both installation and start scripts are ordered. By convention, these scripts are
named with a number prefix, such as 5_autoscaling.sh or 9_agent.sh. These
scripts are said to be in slot 5 or slot 9. All installation scripts in slot 0 are run
before any installation script in slot 1. All of the installation scripts are run in
numeric order, then all of the start scripts are run in numeric order. Set up and
installation scripts are started one time for each virtual machine; start scripts are
started on every boot or restart. For more information, see the section,
Recovery:
Reboot or replace. The workload agent is packaged and installed as a nodepart.
Nodeparts
Nodeparts are installed by the activation script and generally contain binary and
script files to augment the operating system. Review the following information
about nodeparts:
v Conventions

590

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Nodeparts are packaged as .tgz files. The contents are organized into a
directory structure by convention. The following files and directories are
optional:
common/python/maestro/{name}.py
common/scripts/{name}
common/start/{N}_{name}
common/stop/{N}_{name}
{name}/{any files}
setup/setup.py

The root directory is common/ for the following shared files:

common/python
Applies to the Python scripts started by the workload agent including:
- common/python is added to the PYTHONPATH
All files in common/python/maestro/*.py are added to the maestro package
- common/scripts
Added to the PATH before the start scripts are run.
- common/start
Contains script files that are started automatically by the activation script;
scripts are named with a number prefix, for example, 5_autoscaling.sh or
9_agent.sh, and run in numeric order starting with 0_*.
- common/stop
Contains script files that are stopped automatically by the activation script;
scripts are named with a number prefix, for example, 5_autoscaling.sh or
9_agent.sh, and run in reverse numeric order.
{name}/ is a private directory for the nodepart.
setup/ is intended for one-time setup of the nodepart. The script,
setup/setup.py, is started by the activation script with the associated parameters
specified in the topology document. The setup/ directory is deleted after the
setup/setup.py script returns.
v Setup script
If present, the setup/setup.py script is started with the associated parameters.
For example, the workload agent nodepart is configurable for the installation
location, IaaS server and a command port; parameters are specified in the
topology document within the node-part object, such as this excerpt from the
sample topology document in the section, Application model and topology
document examples:
"node-parts":[
{
parms:{
"iaas-port":"8080",
"agent-dir":"\/opt\/IBM\/maestro\/agent",
"http-port":9999,
"iaas-ip":"127.0.0.1"
},
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/agent\/nodeparts\/agent-linux-x64.tgz"
},

The setup/setup.py script can import the maestro module. Configuration

parameters are available as maestro.parms, for example:
import
import
import
import

json
os
subprocess
sys

import maestro
Chapter 7. Managing and deploying virtual patterns

591

parms = maestro.parms
subprocess.call(chmod +x *.sh, shell=True)
rc = subprocess.call(./setup_agent.sh "%s" %d %s %s % (parms[agent-dir],
parms[http-port], parms[iaas-ip], parms[iaas-port]), shell=True)
maestro.check_status(rc, setup_agent.sh: rc == %s % rc)

The implementation is arbitrary. The previous example passes the parameter

values to a shell script, which in turn starts sed for token replacement in the
support scripts.
Nodeparts are generally added to vm-templates during the resolve phase of
deployment. There are two ways that nodeparts are added to a vm-template:
Explicit inclusion as part of a named package.
Implicit inclusion as part of a matching default package.
For example, the config.json file from the workload agent plug-in is shown
here:
{
"name":"agent",
"packages":{
"default":[
{
"requires":{
"arch":"x86_64",
"os":{
"RHEL":"*"
}
},
"node-parts":[
{
"node-part":"nodeparts/agent-linux-x64.tgz",
parms:{
"agent-dir":"/opt/IBM/maestro/agent",
"http-port":9999,
"iaas-ip":"@IAAS_IP@",
"iaas-port":"@IAAS_PORT@"
}
}
]
}
]
}
}

v config.json file
In general, config.json may define any number of named packages. The
previous example shows one package named default. Each package is an array
containing any number of objects, where each object is a candidate combination
of node-parts and/or parts. The candidates are specified by mapped values for
requires, node-parts and parts. Package contents are additive within a pattern
type. For example, if two plug-ins are part of the same pattern type and both
define package FOO in config.json, then resolving package FOO considers
the union of candidates from both config.json files.
default is a special package name. The resolve phase always includes the
default package; other named packages are resolved only when explicitly
named.
Requires

592

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The value of requires is an object that qualifies the candidate in terms of

applicable operating system and architecture. Supported keys and mapped
values are as follows:
Key arch; mapped value is a string or array of strings. Supported strings include
x86 and x86_64 (ESX).
For example,
arch : [x86, x86_64]

Key os; mapped value is an object of os name/version pairs. Supported os name

strings include RHEL and AIX. Valid expressions include the following:
"*" matches all versions
"[a, b]" matches all versions between a and b, inclusive
"(a, b)" matches all versions between a and b, exclusive
"[*, b]" matches all versions up to b, inclusive
"[a, *)" matches all versions a and greater
Package names must be unique across all installed plug-ins, except for the
reserved default package name. The default package is an additive. All plug-ins
can append candidates to the default package and all candidates are
automatically evaluated for a match during the resolve phase of deployment.
Thus, the default package is the basis for implicit inclusion; all other named
packages are only included explicitly.
v Standard nodeparts
All vm-templates include workload agent and firewall nodeparts. Each of the
nodeparts defines a standard interface for integration with and used by other
nodeparts.
Workload agent
The workload agent is an OSGi-based application responsible for installing
parts and driving the life cycle of the roles and dependencies in a plug-in.
The workload agent processes the following sequence of operations to drive
roles and dependencies toward a running application:
1. Get the virtual machine vm-template from the topology document, for
example, if SERVER_NAME == application-was.1, then get the vm-template
named application-was.
2. For each part in the vm-template, run the following sequentially:
a. Download the part .tgz file and extract the file into {tmpdir}.
b. Start {tmpdir}/install.py, passing any associated parameters
specified in the topology document.
c. Delete {tmpdir}.
3. For each role in the vm-template run the following concurrently:
a. Start {role}/install.py, if exists.
b. For each dependency of the role, start {role}/{dependency}/
install.py, if exists.
c. Start {role}/configure.py, if exists.
d. For each dependency of the role, start {role}/{dependency}/
configure.py, if exists.
e. Start {role}/start.py, if exists.
4. React to the changes in the dependencies ({role}/{dependency}/
changed.py) and peers ({role}/changed.py), if exists. Role status is
automatically advanced up to CONFIGURING, but not to RUNNING. A plug-in

Chapter 7. Managing and deploying virtual patterns

593

script must set the role status to RUNNING. Role status is set only by the
{role}/start.py and changed.py scripts (role or dependency). Role status
is set as follows:
import maestro
maestro.role_status = 'RUNNING

There are several custom features of the workload agent, including the
following:
- The workload agent is extensible.
- Other nodeparts can install features into the OSGi-based application.
Complete the following steps to install nodepart features into the agent:
1. Provide a .tgz file containing the following files:
- lib/{name}.jar - bundle Java archive (JAR) files
- lib/features/featureset_{name}.blst - list of bundles for the feature
set
- usr/configuration/{name}.cfg - OSGi configuration code
2. Provide a start script before slot 9 that installs the .tgz file contents into
the agent.
Other nodeparts do not need to know the installation location of the agent
application. Rather, the agent provides the shared script,
agent_install_ext.sh, to install custom features. Shared scripts are always on
the PATH, so a typical start script for a nodepart to install a custom feature is
as follows:
#!/bin/sh
agent_install_ext.sh ../../autoscaling/autoscaling.tgz

The agent_install_ext.sh script extracts the contents of the specified .tgz

file into the agent application. The custom feature is included when the agent
is started.
Firewall
The firewall nodepart defines a generic API for shell scripts and Python
scripts to manipulate the firewall settings on the virtual machine. The default
implementation for RHEL is based on iptables; other implementations can be
built. The firewall.sh script is the shell script provided for Linux. The
following content summarizes the shell usage:
firewall.sh open in [-p <protocol>] [-src <src>]
[-sport <port>] \ [-dest <dest>] [-dport <port>]
firewall.sh open out [-p <protocol>] [-src <src>]
[-sport <port>] \ [-dest <dest>] [-dport <port>]
firewall.sh open tcpin [-src <src>] [-dport <port>]
firewall.sh open tcpout [-dest <dest>] [-dport <port>]
firewall.sh close in [-p <protocol>] [-src <src>]
[-sport <port>] \ [-dest <dest>] [-dport <port>]
firewall.sh close out [-p <protocol>] [-src <src>]
[-sport <port>] \ [-dest <dest>] [-dport <port>]
firewall.sh close tcpin [-src <src>] [-dport <port>]
firewall.sh open tcpout [-dest <dest>] [-dport <port>]

The open tcpin directive is tailored for TCP connections and opens
corresponding rules in the INPUT and OUTPUT tables to allow request and
response connections. The open in directive opens the INPUT table only. For
src and dest, private is a valid value. This value indicates that <src> and

594

IBM Cloud Orchestrator 2.4.0.2: User's Guide

<dest> are limited to the IP range defined for the cloud. The value private is
defined in the config.json file for the firewall plug-in as follows:
{
"name":"firewall",
"packages":{
"default":[
{
"requires":{
"arch":"x86_64",
"os":{
"RHEL":"*"
}
},
"node-parts":[
{
"node-part":"nodeparts/firewall.tgz",
parms:{
"private":"PRIVATE_MASK"
}
}
]
}
]
}
}

Currently, the value of PRIVATE_MASK is set as part of the maestro provisioning

steps. The cloud-specific value is found in the cloud project build.xml file, for
example, cloud.HSLT/build.xml. For an Orion cloud, PRIVATE_MASK ==
10.0.0.0/255.0.0.0.
The Python API is similar. Callers must import the maestro package. The
provided firewall methods are:
maestro.firewall.open_in(**args)
maestro.firewall.open_out(**args)
maestro.firewall.open_tcpin(**args)
maestro.firewall.open_tcpout(**args)
maestro.firewall.close_in(**args)
maestro.firewall.close_out(**args)
maestro.firewall.close_tcpin(**args)
maestro.firewall.close_tcpout(**args)

where **args represents keyword args.

Valid keywords include: protocol,src,sport,dest, and dport.
The following is an example of one valid invocation:
maestro.firewall.open_tcpin(src=private, dport=8080)

Parts
Parts are installed by the workload agent and generally contain binary and life
cycle scripts associated with roles and dependencies. Review the following
information about parts:
v Conventions
All parts must have an install.py script at the root. Additional files are
allowed.
v Common scripts
By default, the maestro package contains the following functions:

Chapter 7. Managing and deploying virtual patterns

595

 maestro.download(url, f): Downloads the resource from the url and saves the
resource locally as file f.
maestro.downloadx(url, d): Downloads and extracts a .zip, .tgz, or .tar.gz
file into directory d. The .tgz and .tar.gz files are streamed through
extraction; the .zip file is downloaded and then extracted.
maestro.decode(s): Decodes strings encoded with the maestro encoding utility,
such as from a transformer using
com.ibm.ws.security.utils.XOREncoder.encode(String).
maestro.install_scripts(d1): Utility function for copying life cycle scripts into
{scriptdir} and making the shell scripts executable (dos2unix and chmod
+x).
maestro.check_status(rc, message): Utility function for logging and exiting a
script for non-zero rc.
v Data objects
The agent appends data objects or dictionaries to the maestro package when
starting part installation scripts as follows:
maestro.parturl : fully-qualified URL from which the part .tgz file was obtained (string; RO)
maestro.filesurl : fully-qualified URL prefix for the shared files in storehouse (string; RO)
maestro.parms : associated parameters specified in the topology document (JSON object; RO)
maestro.node[java] : absolute path to Java executable (string; RO)
maestro.node[deployment.id] : deployment ID, for example, d-xxx (string; RO)
maestro.node[tmpdir] : absolute path to working directory. This path is cleared after use
(string; RO)
maestro.node[scriptdir] : absolute path to the root of the script directory (string; RO)
maestro.node[name] : server name (same as env variable SERVER_NAME) (string; RO)
maestro.node[instance][ private-ip] (string; RO)
maestro.node[instance][ public-ip] (string; RO)
maestro.node[parts] : shared with all Python scripts invoked on this node (JSON object; RW)

Roles
A role represents a managed entity within a virtual application instance. Each role
is described in a topology document by a JSON object, which is contained within a
corresponding vm-template like the following:
maestro.role[tmpdir] : role-specific working directory; not cleared (string; RO)
You can import custom scripts, for example, import my_role/my_lib.py:
utilpath = maestro.node[scriptdir] + /my_role
if not utilpath in sys.path:
sys.path.append(utilpath)
import my_lib

The following is an example role from a topology document:

"roles":[
{
"plugin":"was\/2.0.0.0",
parms:{
"ARCHIVE":"$$1",
"USERID":"virtuser",
"PASSWORD":"$$6"
},
"depends":[
{
"role":"database-db2.DB2",
parms:{
"db_provider":"DB2 Universal JDBC Driver Provider",
"jndiName":"TradeDataSource",
"inst_id":1,
"POOLTIMEOUT":"$$11",

596

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"NONTRAN":false,
"db2jarInstallDir":"\/opt\/db2jar",
"db_type":"DB2",
"db_dsname":"db2ds1",
"resourceRefs":[
{
"moduleName":"tradelite.war",
"resRefName":"jdbc\/TradeDataSource"
}
],
"db_alias":"db21"
},
"type":"DB2",
"bindingType":"javax.sql.DataSource"
}
],

Role state and status

The agent implements a state machine that drives each role through a basic
progression as follows:
INITIAL > INSTALLED > CONFIGURING > STARTING > RUNNING

The role status can change during transitions and within a state. Here is the same
state progression, shown with the details of status and life cycle scripts started:
Table 72. Role state and status
Role state script

Transition

Update status Set role status

Initial

Initial =>
INSTALLED

on entry

INITIAL

during

INSTALLING

INSTALLED

INSTALLED
=>
{role}/install.py then all RUNNING
{role}/{dep}/install.py

CONFIGURING
STARTING (role status by
script)

{role}/configure/py then
all {role}/{dep}/
configure.py
{role}/start.py
RUNNING

on entry
on changed

role_status (set by script)

{role}/start.py

If the process is stopped or an unrecoverable error occurs, move the role to a

TERMINATED or ERROR state. If an error is recoverable, you can keep the role state as
RUNNING and change the role status to FAILED.. For example, if WebSphere
Application Server crashes, and the crash is detected by wasStatus.py. the
wasStatus.py script sets maestro.role_status = "FAILED". When a user starts
WebSphere Application Server from the Virtual Application Console, one of the
following processes occurs:
v If there is no dependency, operation.py sets maestro.role_status="RUNNING".
v If WebSphere Application Server depends on another role (such as DB2),
operation.py sets maestro.role_status="CONFIGURING". The
was/{dep}/changed.py script starts as the result of role status changing from
FAILED to CONFIGURING, and the script starts WebSphere Application Server,
processes dependency info from maestro.deps and sets
maestro.role_status="RUNNING".
Chapter 7. Managing and deploying virtual patterns

597

Two status checks are available that determine when a dependency script is started
on a source role. For example, if A depends on B, then A is the source and B is the
target as follows:
v Role A must be in the RUNNING state (Role.rolesChanged())
v Role B must have status == RUNNING (Relation.rolesChanged())
Existing resources
Plug-ins can interact with existing resources. Although the existing resource is not
a managed entity within the plug-in, it is modeled as a role. This allows for a
consistent approach, whether dealing with pattern-deployed or existing resources.
Specifically:
v Integration between resources is modeled as a dependency between two roles.
The target role (pattern-deployed or existing) exports properties that are used by
a dependency script on the source ({role}/{dep}/changed.py) to realize the
integration. This design provides reuse of the source dependency script. For
example, in the wasdb2 plug-in, the WAS/DB2/changed.py script manages a
WebSphere Application Server data source for any pattern-deployed or existing
database.
v User interactions in the IBM Cloud Orchestrator deployment user interface are
consistent for resources and integrations. Resources (pattern-deployed or
existing) are represented as roles, meaning they display on the Operations tab of
the deployment panel in the product user interface. For example, you can look
for a role when you change a password. For a pattern-deployed resource, the
change is applied to the resource, then exported for dependencies to react. For
an existing resource, change is exported for dependencies to react like when the
password is already changed externally.
Managing configuration of the interactions (links) is handled through the source
role.
An existing resource is modeled by a component in appmodel/metadata.json file.
Typical component attributes are required to connect to the resource, such as
hostname/IP address, port and application credentials.
Integration with existing resources is modeled by a link in the
appmodel/metadata.json file.
If a type of resource displays as pattern-deployed or existing, then consolidation is
possible by adding a role to represent the external resource. This role can export
parameters from the existing resource that the dependent role for the pattern
deployed case can handle.
Consider the case of an application using an existing resource, such as wasdb2,
imsdb and wasctg plug-ins. At the application model level, the existing database is
a component, and WebSphere Application Server uses it, on behalf of the
application, as a represented link to that component. Typical attributes of the
existing database are its host name or IP address and port, and the user ID and
password for access.
In older service approaches, the existing database component has a transform that
builds a JSON target fragment that stores the attributes, and the link transform
uses these attributes. In IMS, for example, the link transform creates a dependency
in the WebSphere Application Server role in the WebSphere Application Server
node, with the parameters of the existing database passed from the component.
The dependent role configure.py script is used to configure WebSphere

598

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Application Server to use the existing database based on the parameters. This is
sufficient, but in the deployment panel, the parameters of the existing database
appear in the WebSphere Application Server role, which is not sensible.
In the new role approach, the target component creates a role JSON object and the
link transform adds it to the WebSphere Application Server virtual machine
template list of roles. The wasdb2 plug-in creates an xDB role to connect to existing
DB2 and Informix databases. IMS can convert to this model, and move its
configure.py and change.py scripts to a new xIMS role. The advantage here is in
the deployment panel, which lists each role for a node separately in a left column
where its parameters and operations, are better separated for user access.
The wasdb2 plug-in provides an additional feature that IMS and CTG might not
use. The plug-in also supports pattern-deployed DB2 instances. In the
pattern-deployed scenario, the DB2 target node is a node that is started. The
correct model is a dependent role and the link configuration occurs when both
components, source WebSphere Application Server and target DB2, start. The
changed.py script is then run. For the existing database scenario, the wasdb2
plug-in exports the same parameters as the DB2 plug-in, and then processing for
pattern-deployed and existing cases can be performed in the changed.py script.
IMS and wasctg do not require this process and can use a configure.py role script
for new roles.
Set repeatable task
At run time, a role might need to perform some actions repeatedly. For example,
the logging service must back up local logs to the remote server in a fixed period.
The plug-in framework allows a script that is started after a specified time, to meet
this requirement.
In any part script, such as configure.py and start.py, you can specify a task as
follows:
task = {}
task[script]=backupLog.py
task[interval] = 10
taskParms={}
taskParms[hostname] = hostname
taskParms[directory] = directory
taskParms[user] = user
taskParms[keyFile] = keyFile
task[parms] = taskParms
maestro.tasks.append(task)

You must have a dictionary object named task. You can change this to another
valid name. The target script is specified by task[script'] and the interval is
specified by task[interval']. You can add parameters to the script by using
task[parms']. This is an optional addition to the script. The,
maestro.tasks.append(task) is used to enable this task. In this sample,
backupLog.py, which is located in the folder {role}/scripts, is started after 10
seconds when the current script is completed. Using the backupLog.py script, you
can retrieve the task parameters from maestro.task[parms'] and retrieve the
internal from maestro.task[interval']. This script is only started one time. If the
backupLog.py script is required to be started repeatedly, you must add the same
codes into the backupLog.py script. When the current script is completed, it is
started after the new specified internal and parameters.
Chapter 7. Managing and deploying virtual patterns

599

Recovery: Reboot or replace?

If a virtual machine stops unexpectedly, the master agent recovers the failed virtual
machine. The action depends on the virtual machine type. A persistent virtual
machine is rebooted. Other virtual machines are replaced.
A virtual machine is persistent if it is an instance of a vm-template with a
true-valued persistent property, as follows:
"vm-templates": [
{
"persistent":true,
"scaling": {
"min": 1,
"max": 1
},

There are two ways for a plug-in to mark a virtual machine as persistent:
v Direct
The transformer adds the persistent property to the vm-template.
v Indirect
The package configuration specifies the persistent attribute.
The direct method supersedes the indirect. That is, if the vm-template is marked
persistent (true or false), that is the final value. If the vm-template is not marked
persistent, the resolve phase of deployment derives a persistent value for the
vm-template based on the packages associated with that vm-template. The
vm-template is marked persistent or true if any package declares persistent true.
The indirect method provides more flexibility to integrate parts and node parts,
without requiring global knowledge of where persistence is required. A
transformer adds the property as follows:
"vm-templates": [
{
"persistent":true,
"scaling": {
"min": 1,
"max": 1
},
"name": "Caching_Master",
"roles": [
{
"depends": [{
"role": "Caching_Slave.Caching"
}],
"type": "CachingMaster",
"name": "Caching",
parms:{
"PASSWORD": "$XSAPassword"
}
}
],
"packages": [
"CACHING"
]
},

Package configuration is specified in the config.json file as follows:

{
"name" : "db2",
"version" : "1.0.0.0",

600

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"packages" : {
"DB2" : [{
"requires" : {
"arch" : "x86_64",
"memory" : 0},
"persistent" : true,
"parts" : [
{"part" : "parts/db2-9.7.0.3.tgz",
parms : {
"installDir" : "/opt/ibm/db2/V9.7"}},
{"part" : "parts/db2.scripts.tgz"}]
}]
}
}

Virtual Application Console

You can view the virtual application instances through the Operations tab of the
Virtual Application Console.
Operation
v Define an operation.
Create a JSON file named, operation.json, in the plugin/appmodel directory.
Each operation.json file should contain a JSONObject. The following code
example shows a part of the WebSphere Application Server operation.json file,
where the key is the role type WAS, and the value is a JSONArray that contains
these operation definitions:
"WAS":
[
{
"id": "setWASTrace",
"label": "TRACE_LEVEL_LABEL",
"description": "TRACE_LEVEL_DESCRIPTION",
"script": "debug.py setWASTrace",
"attributes": [
{
"label": "TRACE_STRING_LABEL",
"type": "string",
"id": "traceString",
"description": "TRACE_STRING_DESCRIPTION"
}
]
},

where
script defines the operation debug.py script that is started when the operation
is submitted. The operation script name can also be followed by a method
name such as setWASTrace that is included in the previous code sample. The
method name can be retrieved later in the operation script. The operation
script should be placed under the role scripts path, for example,
plugin/parts/was.scripts/scripts/WAS.
attributes define the operation parameters that you must input. The operation
parameters can be retrieved later by the operation script.
v Attributes for operations against multiple instances.
If a role has more than one instance, you can use these attributes in the
operation definition to control how an operation is applied to instances. The
following attributes are validated if a role has more than one instance:

Chapter 7. Managing and deploying virtual patterns

601

rolling
Determines if an operation is performed sequentially or concurrently on
instances.
To perform an operation concurrently, set "rolling": false. This is
the default setting.
To perform an operation sequentially, set "rolling": true
target Determines if an operation is performed on a single instance or all
instances.
To perform an operation on all instances, set "target": All. This is
the default setting.
To perform an operation a single instance, set "target": Single
See the WebSphere Application Server operation.json file for an example.
v Setting a particular role status for an operation.
By default, when an operation is being performed, the role status is set to
"CONFIGURING" and then is set back to "RUNNING" when the operation is
complete. This change in status can sometimes stop the application itself. Some
operations, such as exporting logs, do not require a role to change its status from
"RUNNING". For these types of operations, you can explicitly set the role status
to use when the operation starts. For example, to keep the role status as
"RUNNING" when the operation starts, add the following attribute to the
operation definition:
"preset_status": "RUNNING"

The role status will remain as "RUNNING" unless an error occurs during the
operation.
See the WebSphere Application Server operation.json file for an example
v Operation script
The operation script can import the maestro module. The information retrieved
in the role life cycle part script can be retrieved the same way in the deployment
panel, such as maestro.role, maestro.node, maestro.parms, and maestro.xparms.
Also, all of the utility methods, such as download and downloadx, can be used.
Parameters that are configured at the deployment panel are passed into the
script and are retrieved at maestro.operation['parms]. The method name
defined in the operation.json file is retrieved at maestro.operation['method],
and operation ID is retrieved at maestro.operation['id].
v File download and upload
All downloaded artifacts must be placed under the fixed root path. The
operation script can get the root path from
maestro.operation['artifacts_path]. To specify a file downloaded later, insert
maestro.return_value=file://key.p12 in the script. The prefix, file://,
indicates that a file is required for download. After the script is complete, the
deployment panel displays a link to download the file. Uploaded files are placed
in a temporary folder under the deployment path in the storehouse. The
operation script retrieves the full storehouse path of the uploaded files, for
example:
uploaded_file_path=maestro.operation['parms][{parm_name}]

After the file path is retrieved, the maestro.download() method downloads the
file. When the operation is complete, the temporary files in storehouse are
deleted. When the operation script interacts with kernel services and storehouse,
the script prefers to use the authorization token passed from the user interface,
but not use the agent token, so that the operations can be audited later. The

602

IBM Cloud Orchestrator 2.4.0.2: User's Guide

operation script should use maestro.operation["user_token"]) to retrieve the user

token passed from the user interface, which contains user uuID. You can use it
later in communication with kernel services and storehouse. For example, to
upload a file into storehouse, use upload_if_new(url, file) which uses
agent_token to generate the authorization header. You can also use
upload_if_new(url, file, user_token), where the passed-in user_token is used to
generate the header.
v Operation result
You can specify the result of an operation using
maestro.operation[successful']=True/False. The default value is True. After the
operation script completes successfully, the user interface displays the result as
SUCCESS or FAIL. If the script ran with failures such as return code!=0, the user
interface result displays as ERROR, and the responding role changes to ERROR
state. If you want a more meaningful result returned, insert
maestro.operation[return_value']=my return value. The return value displays
on the user interface when the script completes.
v Depends-on role operation
In some scenarios, one role update causes another role to also need an update.
This is called the depends-on role operation. An example of this is if DB2
changes a password, WebSphere Application Server also updates the data source
configuration. In the operation script, export the changed value, such as:
maestro.export[DB_PASSWORD']="<XOR>UIK8CNz. Then, change the
depends-on role changed.py script, to add code to handle the other update.
if len(updated)== 1:
myrole = updated[0]
if deps[myrole] [is_export_changed] :
print export data changed
else:
print only status changed

Configuration
In the deployment panel, a configuration update is handled as a special type of
operation. The configuration processes include:
v Define a configuration.
Add the tweak.json file under the plug-in plugin/appmodel folder, to specify
which configuration parameters can be changed during run time. This means
that some parameters in the topology model can be changed and validated at
run time. Each tweak.json file is a JSONArray. Each object describes a parameter
that can be tweaked in the topology model. For example, in the WebSphere
Application Server plug-in, add the following code example to a tweak.json file.
The parameter "ARCHIVE" under the "WAS" role can be tweaked.
The value of "id" is composed with {role_type}.{parm_name}. Other attributes
such as "label" and "description" are prepared for the user interface. This is
similar to the definition in the metadata.json file located in the /appmodel
directory.
{
"id": "WAS.ARCHIVE",
"label":"WAR/EAR File",
"description":"Specifies the web/enterprise application to be uploaded. ",
"type":"file",
"extensions":[
"war",
"ear"
]
}
Chapter 7. Managing and deploying virtual patterns

603

For a parameter under the depends section, the value of "id" is composed with
{role_type}.{depends_role_type}.{parm_name}:
{
"id": "WAS.DB2.MINPOOLSIZE",
"type": "number"
}

To enable this feature, you must add the following code to the operation.json
file:
{
"id": "configuration",
"label": "CONFIGURATION_LABEL",
"description": "CONFIGURATION_DESCRIPTION",
"script": "change.py"
},

v Configuration script: change.py

The change.py script is similar to the operation script, except for the following:
When you use the depends role configuration, the change.py script is placed
under the plugin/parts/{parts_package}/scripts/{role_type}/
{depends_role_type} path.
After the script is started successfully, the changed values are automatically
persisted to storehouse.
For the artifacts-type configuration update, such as when you update the
WebSphere Application Server ARCHIVE, if the change.py script completes
successfully, the artifacts in temp folder in storehouse are cloned to the
/deployment/{deployment_id}/artifacts path before they are deleted.
v Configuration for non-role component, such as remote DB2 and Tivoli Directory
Service.
If the transformer needs configuring, use wasxdb2 as shown in the example:
In XDB2Transformer.java:
Change
result.put("service", attributes);

to
result.put("attributes", attributes);
result.put("service", prefix);

In WASXDB2Transformer.java:
Change
JSONObject serviceParms = (JSONObject) targetFragment.get("service);

To
JSONObject serviceParms = (JSONObject) targetFragment.get("attributes);

and add following line:

//WASxDB2 acts as an extension, not a dependency (so, no role defined)
depend.put("type", "xDB2");
depend.put("service", targetFragment.get (service));

v Configuration for multi-links between two components, such as remote

WebSphere Application Server and Tivoli Directory Service.
Besides the tweak.json file, the transformer needs specific codes to handle this
scenario. The target topology segment should look like the following:
"depends": [
{
"role": "User_Registry-tds.TDS1",

604

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"deps_key_id": "WAS.xLDAP.xLDAP_ROLE_MAPPING",
parms: {
"manager": {
"SPECIALSUBJECTS_xLDAP_ROLE_MAPPING": "None",
"GROUP_xLDAP_ROLE_MAPPING": "manager",
"xLDAP_ROLE_MAPPING": "manager",
"USER_xLDAP_ROLE_MAPPING": ""
},
"employee": {
"USER_xLDAP_ROLE_MAPPING": "",
"GROUP_xLDAP_ROLE_MAPPING": "employee",
"xLDAP_ROLE_MAPPING": "employee",
"SPECIALSUBJECTS_xLDAP_ROLE_MAPPING": "None"
}
}
}
]

The parms are nested structure and you must specify a deps_key_id as the
key for the subgroup in the parms. You can use Java based code or a template
to complete the transformer. In parts scripts changed.py and change.py, you can
retrieve the parameters using for cycle as follows:
for key in parms:
roleParms = parms[key]
print key
print roleParms[xLDAP_ROLE_USER_MAPPING]
print roleParms[xLDAP_ROLE_GROUP_MAPPING]
print roleParms[xLDAP_SPECIAL_SUBJECTS_MAPPING]

Other reference
See the related links for references to JSON formatting and validation, and,
guidelines for starting external commands from Python scripts.
Application model and topology document examples
The application model and topology documents are core pieces of the IBM Cloud
Orchestrator modeling and deployment. This section presents examples of these
related documents as a basis for the other sections in this guide. The sample Java
Enterprise Edition (Java EE) web application provided with the web application
virtual application pattern type is used as an example.
Application model
The appmodel.json file represents the serialization of the model that is defined in
the Pattern Builder user interface. Components (nodes) and links, along with
user-specified property values, are represented.
{
"model":{
"name":"Sample",
"nodes":[
{
"attributes":{
"WAS_Version":"7.0",
"archive":"artifacts/tradelite.ear",
"clientInactivityTimeout":60,
"asyncResponseTimeout":120,
"propogatedOrBMTTranLifetimeTimeout":300,
"totalTranLifetimeTimeout":120
},
"id":"application",
"type":"EAR"
Chapter 7. Managing and deploying virtual patterns

605

},
{
"attributes":{
"dbSQLFile":"artifacts/setup_db.sql"
},
"id":"database",
"type":"DB2"
}
],
"links":[
{
"source":"application",
"target":"database",
"annotation":"",
"attributes":{
"connectionTimeout":180,
"nontransactional":false,
"minConnectionPool":1,
"jndiDataSource":"jdbc/TradeDataSource",
"XADataSource":false,
"maxConnectionPool":10
},
"type":"WASDB2",
"id":"WASDB2_1"
}
]
}
}

Topology document
The final topology document for a given application model depends on the
deployment environment, such as storehouse URL and image ID. This sample
shows two vm-templates from the web application, application-was and
database-db2. Each vm-template has a list of nodeparts and parts to be installed,
and run time roles to be managed.
{
"vm-templates":[
{
"parts":[
{
"part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/was\/parts\/was-7.0.0.11.tgz",
parms:{
"installDir":"\/opt"
}
},
{
"part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/was\/parts\/was.scripts.tgz"
},
{
"part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/wasdb2\/parts\/db2.jdbc.tgz",
parms:{
"installDir":"\/opt\/db2jar"
}
},
{
"part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/wasdb2\/parts\/wasdb2.scripts.tgz"
}
],
"node-parts":[
{
parms:{
"private":"127.0.0.1"
},
"node-part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/firewall\/nodeparts\/firewall.tgz"
},
{
parms:{
"iaas-port":"8080",
"agent-dir":"\/opt\/IBM\/maestro\/agent",
"http-port":9999,

606

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"iaas-ip":"127.0.0.1"
},
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/agent\/nodeparts\/agent-linux-x64.tgz"
},
{
parms:{
"installerURL":"files\/itmosv6.2.2fp2_linuxx64.tar.gz",
"omnibustarget":"",
"temsip":"",
"omnibusip":""
},
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/monitoring\/nodeparts\/monitoring.tgz"
},
{
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/deployinlet\/nodeparts\/deployinlet.tgz"
},
{
parms:{
"collectors":[
{
"url":"https:\/\/2.zoppoz.workers.dev:443\/http\/COLLECTOR_NODE_IP:8080"
}
]
},
"node-part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/logging\/nodeparts\/logging.tgz"
},
{
"node-part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/cloud.HSLT\/nodeparts\/iaas.tgz"
},
{
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/autoscaling\/nodeparts\/autoscaling.tgz"
}
],
"scaling":{
"min":1,
"max":1
},
"image":{
"type":"medium",
"image-id":"none",
"activators":[
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/\/admin\/clouds\/mockec2.zip"
]
},
"name":"application-was",
"roles":[
{
"depends":[
{
"role":"database-db2.DB2",
parms:{
"MAXPOOLSIZE":"$$2",
"installDir":"\/opt\/db2jar",
"inst_id":1,
"POOLTIMEOUT":180,
"NONTRAN":false,
"DS_JNDI":"jdbc\/TradeDataSource",
"MINPOOLSIZE":"$$3"
},
"type":"DB2"
}
],
parms:{
"clientInactivityTimeout":"60",
"ARCHIVE":"$$1",
"propogatedOrBMTTranLifetimeTimeout":"300",
"asyncResponseTimeout":"120",
"USERID":"virtuser",
"totalTranLifetimeTimeout":"120",
"PASSWORD":"<xor>BW4SbzM9FhwuFgUxE2YyOW4="
},
"external-uri":"http:\/\/{SERVER}:9080\/",
"type":"WAS",
"name":"WAS",
"requires":{
"memory":256

Chapter 7. Managing and deploying virtual patterns

607

}
}
],
"packages":[
"WAS",
"WASDB2"
]
},
{
"parts":[
{
"part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/db2\/parts\/db2-9.7.0.1.tgz",
parms:{
"installDir":"\/opt\/ibm\/db2\/V9.7"
}
},
{
"part":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/db2\/parts\/db2.scripts.tgz"
}
],
"node-parts":[
{
parms:{
"private":"127.0.0.1"
},
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/firewall\/nodeparts\/firewall.tgz"
},
{
parms:{
"iaas-port":"8080",
"agent-dir":"\/opt\/IBM\/maestro\/agent",
"http-port":9999,
"iaas-ip":"127.0.0.1"
},
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/agent\/nodeparts\/agent-linux-x64.tgz"
},
{
parms:{
"installerURL":"files\/itmos-v6.2.2fp2_linuxx64.tar.gz",
"omnibustarget":"",
"temsip":"",
"omnibusip":""
},
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/monitoring\/nodeparts\/monitoring.tgz"
},
{
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/deployinlet\/nodeparts\/deployinlet.tgz"
},
{
parms:{
"collectors":[
{
"url":"https:\/\/2.zoppoz.workers.dev:443\/http\/COLLECTOR_NODE_IP:8080"
}
]
},
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/logging\/nodeparts\/logging.tgz"
},
{
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/cloud.HSLT\/nodeparts\/iaas.tgz"
},
{
"node-part":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/admin\/plugins\/autoscaling\/nodeparts\/autoscaling.tgz"
}
],
"scaling":{
"min":1,
"max":1
},
"image":{
"type":"large",
"image-id":"none",
"activators":[

608

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/\/admin\/clouds\/mockec2.zip"
]
},
"name":"database-db2",
"roles":[
{
parms:{
"DB_PORT":50000,
"DB_PATH":"\/home\/db2inst1",
"PASSWORD":"<xor>NRA0aWgHOGoRaG47DiU=",
"DB_NAME":"adb",
"SQL_URL":
"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9444\/storehouse\/user\/applications\
/a-0d1ac0d4-4e4c-49d7-954f-d4884a6ad703\/artifacts\/setup_db.sql"
},
"external-uri":"jdbc:db2:\/\/{SERVER}:50000\/adb:user=db2inst1;password=jOk67Xg5N71dQz;",
"type":"DB2",
"name":"DB2"
}
],
"packages":[
"DB2"
]
}
]
}

Related information:
JSON Formatter and Validator
JSONLint: The JSON Validator
Python documentation: Subprocess management
Plug-ins for development:
The Plug-in Development Kit (PDK) includes several plug-ins that you can install
to assist you with testing and troubleshooting your plug-ins.
Debug:
The debug component, com.ibm.maestro.plugin.debug, provides support for
developing and debugging plug-ins.
Before you begin
The debug component is included in the IBM Plug-in Development Kit.
Before you can use the debug plug-in, you must import it into your IBM Cloud
Orchestrator development environment.
1. Import the com.ibm.maestro.plugin.debug plug-in.
2. Restart IBM Cloud Orchestrator.
About this task
The following are the attributes for the debug component:
v Do not deploy this application model, only write topology document to
storehouse: Select this option to specify the use of the Storehouse Browser to get
a topology document.
This option enables a deploy-only mode so that your virtual application pattern
is transformed through the complete deployment process, but no virtual
machines are created. Rather, the finalized topology document is written to the
Storehouse. You can use the Storehouse Browser to view your final topology
document.
Chapter 7. Managing and deploying virtual patterns

609

Using this option is the first debugging step after writing the plug-in and
pattern type. To locate the Storehouse Browser, access the product user interface.
From the menu, click System > Storehouse Browser. Expand User Deployments
> deployment ID. Click topology.json > Get Contents.
The deployment ID is in the Kernel Services (KS) console log, as follows:
[18/Aug/2011 21:19:54:447 +0000] INFO debug topology-only deployment stored topology
document in https://192.0.2.10:9444/storehouse/user/deployments/
d-02de78c2-6b26-4f32-80af-ba9083a481c4/topology.json

v Leave files on deployed nodes to enable manual debugging: Select this option
if you want to use Secure Shell (SSH) to access the node for manual debugging.
The virtual application pattern is deployed when this check box is selected.
Virtual machines are created in the deployment process.
The files are retained on deployed virtual machines so that you can log in to the
machines with SSH. You can view files and re-run nodepart and part life-cycle
scripts. This option supports greater productivity in debugging these scripts,
because you can edit and re-run scripts on the node and are not required to
fully deploy new nodes to start a test cycle. See Running Scripts on deployed
virtual machines for instructions on using this option.
Procedure
You can view, edit, or add this virtual application component in the user interface
as follows:
1. Click PATTERNS > Pattern Design > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Pattern Builder palette.
4. To add the debug component to a virtual application pattern, click Debug
listed under Other Components and drag the icon to the Pattern Builder
canvas. The properties panel for the database component displays to the right
of the Pattern Builder palette. For more details on the properties panel settings,
view the help by selecting the help icon on the properties panel.
5. To edit an existing debug component, select the Debug part on the Pattern
Builder canvas. The properties panel displays. For more details on the
properties panel settings, see the properties descriptions or view the help by
selecting the help icon on the properties panel.
For more details on the properties panel settings, view the help by selecting the
help icon on the properties panel.
6. You can also view the debug component properties by viewing the plug-in
information.
Click PATTERNS > Deployer Configuration > System Plug-ins. Select
Foundation Pattern Type from the Select a pattern type menu.
The plug-ins included with the Foundation Pattern are listed. Select
com.ibm.maestro.plugin.debug/x.x.x.x from the System Plug-ins palette where
x.x.x.x corresponds to the version numbers. The component plug-in
configuration information displays on the canvas.
Results
You have edited a current component, edited an existing component, or added one.

610

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Unlock:
To facilitate plug-in development, the unlock plug-in provides the ability to delete
a plug-in used by a virtual application instance so that you can easily replace the
plug-in with an updated version and activate the new plug-in on existing virtual
machines instead of redeploying a new copy of the application.
Before you begin
Important: The unlock plug-in is for development environments only to facilitate
testing of plug-ins that are being developed. It is not intended for production
environments and should not be installed in a production environment.
About this task
The debug component is included in the IBM Plug-in Development Kit.
In a normal IBM Cloud Orchestrator environment, a plug-in cannot be removed if
it is being used by a deployed virtual application. For example, if a virtual
application uses a plug-in called custom.plugin at the version level 1.2.3.4, you
cannot delete version 1.2.3.4 of custom.plugin from the system. Locking the
plug-in in this way is important for the integrity and stability of virtual
applications in a production environment. If the plug-in is removed and the
deployed application needs to scale up or recover from a failure, the absence of the
plug-in can result in application failure.
In a development environment, however, the ability to delete and replace a locked
plug-in is useful because it significantly reduces the time required to test updates
to a plug-in. For example, if a deployed application is using custom.plugin version
1.2.3.4 and you want to test a bug fix or new feature that you have added to the
plug-in, you can import the modified custom.plugin version 1.2.3.4 plug-in and
activate it on deployed virtual machines in the virtual application instead of
deploying a new copy of the virtual application.
Procedure
To use the unlock for plug-in testing:
1. Update the code for the plug-in you are developing, and build the plug-in
without changing the version number of the plug-in.
2. Import the plugin.unlock plug-in and then restart IBM Cloud Orchestrator.
3. Delete the existing plug-in version from the IBM Cloud Orchestrator system.
4. Import the plug-in that you updated and built in step 1.
5. Apply the changes to the virtual machine.
a. Stop the agent and deployment inlet.
killall java

b. Remove installed artifacts with the following commands:

rm -rf /opt/IBM/maestro
cd /0config
rm -rf 0config.log backup/ cert.tmp/ debug/ doneconfig download.zip exec_vm_tmpl/
itlm/ lafiles/ logging/ monitor/ nodepkgs/ properties/ start/

c. Perform any operations required to put the virtual machine in a state that is
ready for a fresh activation of the plug-in. This can include stopping
processes or removing files or other content that the plug-in installs on the
virtual machine.
Chapter 7. Managing and deploying virtual patterns

611

d. Restart the virtual machine and activate the plug-in with the following
command:
/0config/0config.sh

The node reboots and restarts itself, as if it were a newly deployed node. It
downloads the topology document, and then takes the nodeparts, parts, and
roles through all the lifecycle events by running all the lifecycle startup
scripts. Your newly installed version 1.2.3.4 of custom.plugin is used by the
application. You can restart as many virtual machines as you need to
properly test your plug-in code.
What to do next
If you need to update the plug-in again, you can repeat the steps to delete the
installed plug-in, import the modified version, and activate the new version on the
virtual machines. When you finished your testing, delete plugin.unlock and restart
IBM Cloud Orchestrator.
Creating your own database plug-in:
If you want to develop a plug-in to support your own database, you can create
own modeled on wasdb2 plug-in. This topic describes how the implementation of
a database connection.
The wasdb2 plug-in includes parts for connections with an existing DB2, Informix,
or Oracle, or connections with a pattern-deployed DB2 database. You can choose to
include either or both implementations in your custom plug-in.
For a pattern-deployed database, there are two virtual machines, one running
WebSphere Application Server with the user's application, and the other running
DB2 to manage data for the application. In the existing database case, the database
is already up and running on another machine, either in the cloud, as a shared
service, or outside the cloud managed by IBM Cloud Orchestrator. In either case,
WebSphere Application Server needs to have the IP address, port number, database
name, and database credentials (userid and password) to connect to the database.
In the application model, the WebSphere Application Server node and the database
node are modeled as components. The link between them in the application model
represents the connection between them, and provides the foundation for this data
transfer of required access information.
Pattern-deployed database connection
Roles provide capabilities to orchestrate application startup, life-cycle management,
and undeployment. For a database deployed with the IBM Web Application
Pattern (not released with the product), a WAS role manages and interacts with
WebSphere Application Server instance deployed on its node, and a DB2 role
interacts with the DB2 instance deployed on its node. The wasdb2 plugin provides
a link between the WAS and DB2 components. It inserts a dependency of the WAS
role on the DB2 role. At the start of the deployment, when both the WAS and DB2
roles transition to the RUNNING state, the WAS/DB2/changed.py script runs. The
DB2 role life-cycle scripts export DB2 characteristics, like hostname/IP address,
port number, database name, userid and password that are required to use the DB2
database on this deployed instance. The WAS/DB2/changed.py script gets this
exported data, and passes the values into wsadmin scripts to configure the
information so that applications in the WebSphere Application Server node can
access the database.

612

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Roles can also contribute operations to the deployment inlet. These operations can
be used to modify the running deployment. For example, you can change the
password of your DB2 database. The DB2 plugin offers this operation, which
changes the database password and exports this changed data. The
WAS/DB2/changed.py script is notified on this update, and invokes a wsadmin
script to update the changed password in WebSphere Application Server.
Existing database connection
Web Application Pattern (not released with the product) supports connecting to
three existing database types: DB2, Informix, or Oracle. It uses a role for each:
xDB2, xInformix and xOracle. These roles work like the DB2 role used for a
pattern-deployed database. An application model component is available on the
Pattern Builder palette for each type of database, with hostname/IP address, port
number, database name, and user ID and password attributes. These values are
specified at virtual application design time. A link transform makes the WAS role
dependent on these roles, for existing databases. The xDB2 role start.py script
exports the values that are specified in xDB2 component on the Pattern Builder
pane, by using the same mechanism and key names as the DB2 role. The existing
database roles offer configuration settings and deployment inlet change operations
to dynamically change these configuration values just like the DB2 role. As with a
pattern-deployed DB2 database, WAS/xDB/changed.py scripts get the exported
xDB values (IP address, port number, database name, userid and password) and
invoke appropriate WebSphere Application Server configuration scripts so that the
applications on the WebSphere Application Server node can access the database.
Two attributes must be added to dependent roles.
asDependency : DB
Normally, each dependent role must provide its own dependent role scripts.
The wasdb plugin provides these scripts for all databases, and they are
delivered as WAS/DB scripts. While the topology document has the WAS role
depending on the appropriate DB role (DB2, xDB2, xInformix or xOracle), the
asDependency attribute maps all dependent role script calls to WAS/DB, for
example for changed.py. Database dependent information, unique to each
database, is passed to the wasdb link in a dblink_metadata JSONObject.
localOnly : true
This attribute is used in the existing resource or surrogate role cases to indicate
that this role is local to the WebSphere Application Server node. It is especially
important with scaling to invoke WAS/DB/changed.py only once per local
WebSphere Application Server node. The next section describes surrogate roles.
The wasdb plugin contributes a WASDB link to the Web Application Pattern
pattern type. The source component is a WebSphere Application Server node
(vm-template). The target component is a JSONObject with two elements:
dblink_metadata (required
A JSONObject with two elements:
packages (optional)
A JSONArray of package names to be installed on the WebSphere
Application Server node. The packages are added in the usual way to the
$sourcePackages variable in the wasdb_link.vm velocity template.
parms (required)
The database-specific parameters required by the scripts to configure Web
Application Pattern to connect to the database
Chapter 7. Managing and deploying virtual patterns

613

role (optional)
The role to insert into the WebSphere Application Server template. It is also
made a dependent role to the WAS role in the source WebSphere Application
Server template, as is usual in Velocity template link transforms. The role
element is used in the existing database case, for xDB2, xInformix and xOracle.
A pattern-deployed database does not need an extra role. It uses the DB2 role
for the WAS role to depend on. A targetRole parameter is included in the
dblink_metadata parms element for a pattern-deployed database. Its value is
the name of the pattern-deployed DB role of the dependency added to the
WAS role.
Using a surrogate role
The surrogate role is an option if your database pattern deploy plug-in does not
provide a role that closely mimicks the DB2 role, or the data it exports does not
use the same names as the DB2 role and our xDB roles. A surrogate role is added
to reflect status and changes in the target database role back to the wasdb plugin
in the manner it expects. For example, a database called DB3 has a DB3 role, that
we want to use with our wasdb plugin. We will create a new role, DB3Surrogate,
that depends on the DB3 role. It will have a DB3Surrogate/DB3/changed.py script
that gets changed exported data from DB3. The WAS role will be dependent on
DB3Surrogate role, which will export changed data from DB3, convert it to names
and formats expected by wasdb, and export it in names wasdb expects. To realize
this with WASDB link, targetRole in dblink_metadata parms would be DB3, and
the DB3Surrogate role would be passed in as the role element.
Log service for plug-ins:
The logging service is a general service to collect multiple types of information.
The information is securely transferred from the virtual machine and stored for
review by a logging service implementation.
The information collected by the logging service is for administrative purposes and
not for the application. The service can collect text and binary type file
information. The file can be a single snapshot file that is never collected again or
an infinitely growing file that can rotate to manage the size.
The logging service is a high-level service that supports zero to multiple registered
logging service implementations. The registered implementations are the real
processes that provide reports on the multiple types of information collected.
This general logging service presents a subset of the collected information in the
Log Viewer page of the IBM Cloud Orchestrator user interface and the Virtual
Application Console deployment Log Viewer tab.
The Log Viewer displays only the information found on the virtual machine when
requested. Historical information cannot be displayed when the information is
removed. For example, if the data is deleted or rolled over or if the virtual
machine disappears because it is terminated. The presentation of the historical
information, even after the virtual machine is no longer available, remains
available to the logging service implementation to extend the Log Viewer
capabilities to access the extracted information such as the external storage system.
The logging service information is explained in more detailed in the following
sections:

614

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v High-level design of the log service

v Plug-in interaction with the log service on page 618
v Create a log service implementation on page 618
High-level design of the log service
The logging service is automatically included on all virtual machines that have the
IBM Cloud Orchestrator agent. Included is the virtual application virtual machines.
The logging service is a generic framework for plug-ins to use, notifying the
logging service implementation about the multiple types of information to collect.
This provides the flexibility for different logging service implementations to be
registered on a single virtual machine. When notifying the logging service about
the list of files to collect, specific information is required that helps all logging
service implementations. The logging service uses a logtype, such as name, type,
and single event pattern, and a list of specific files or directories that are
pattern-based or any file created in directory, to monitor. The type and single event
pattern helps the logging service understand details about the file, like how
individual events are contained inside the file. The logging service provides a
default list of logtypes that can be used and information how to extend the list of
logtypes for the custom event patterns described as follows.
Logging service default list of logtypes
This section describes the default list of logtypes. Using these logtypes reduces the
need for creating custom logtypes. These logtypes can be used by external
resources to monitor the files or directories.
Table 73. Logtypes. List of logtypes and details
Logtype name

Logtype details

File

"description":"Single file created for log

entry"

BinaryFile

"description":"Single binary file created for

log entry"

SingleLine

"description":"Each list is a new entry"

MultiLineTimeStamp

"description":"Single/Multi line entry where

bracket incase
date/time, [10/8/10 16:42:54:109 EDT], notes
the start of a new entry", "start":
"\\[\\d{1,2}/\\d{1,2}/\\d{2}.*\\d{1,2}:\\
d{2}:\\d{2}:\\d{3}.*\\w{1,3}\\].*"

MultiLineIP

"description":"Single/Multi line entry where

IP address notes the start of a new entry",
"start": "\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\
.\\d{1,3}.*"

Custom logtypes
External resources can create a custom logtype to assist custom event patterns in
monitoring the files and directories. This is done by creating a custom JSON file
packaged with the external resource. The plug-in must notify the logging service
about this custom logtype file. The basic metadata fields for a logtype entry are as
follows:
Chapter 7. Managing and deploying virtual patterns

615

Table 74. Custom logtypes. List of custom logtypes and details

Metadata field ID

Value

Required

name

Specifies a unique name.

True

description

Specifies a text description of False

the logtype

format

Specifies either binary or

text. The default is text.

False

start

Specifies a pattern to
determine where an event
starts.
Important: If no end tag is
included, an event ends
when the pattern is seen
again.

False

end

Specifies a pattern to
determine when an event is
complete.
Important: This tag
determines when an event is
complete, therefore, other
start patterns that are found
are ignored until the end
pattern is found.

False

Example
logtype-config.json file:
{"types":[
{
name": adaptorName2,
"description":This is a new adaptor",
format:text
"start": "\\[\\d{2}/\\w{3}/\\d{4}.*\\d{2}:\\d{2}:\\d{2}:\\d{3}.*\\-\\d{4}\\].*Start:.*",
"end": "\\[\\d{2}/\\w{3}/\\d{4}.*\\d{2}:\\d{2}:\\d{2}:\\d{3}.*\\-\\d{4}\\].*End:.*"
}
]}

Logging service methods

Plug-in Python life cycle scripts interact with the logging service through the
maestro.loggingUtil method call. The following list includes methods that the
logging service utility exposes for plug-ins to call:
v maestro.loggingUtil.registerImplementation(ImplName, ImplScript)
Allows the logging service implementations to register with the general logging
service. This method indicates if the logging services are the local virtual
machine implementations. When registered, the maestro.loggingUtil monitor,
unmonitor and registerPluginLogtype calls are forwarded to the registered
implementation.
Input: ImplName Specifies the name of the logging service implementation.
Input: ImplScript Specifies the path and file name of the Python script that
is implementing the monitor, unmonitor and registerPluginLogtype
calls.
Return: Specifies true if the call successfully completes or false if the call
fails.
v maestro.loggingUtil.unregisterImplementation(ImplName)

616

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Allows the logging service implementations to unregister with the general

logging service. This stops the forwarding of the monitor, unmonitor and
registerPluginLogtype calls to the service implementation.
Input: ImplName Specifies the name of the logging service implementation.
Return: Specifies true if successfully complete or false if fails.
v maestro.loggingUtil.monitor(listjson)
Allows the plug-in to notify the logging service implementations about the list
of files and directories to monitor. This object indicates the specific role and lists
the files to be collected. Details about the files, such as location and logtype, are
provided. The location and logtype explain the structure of a single event inside
the file for indexing implementations. The implementation must handle multiple
duplicate invocations of this call.
Input: jsonData Specifies a JSON list that contains the details about a
specific role list of information to monitor. The structure of this object is as
follows: { "role": "<roleName>", "types": [ { "logtype": "<logtypeName>", "type":
"<file or directory>", "name": "<path with or without a file name>", "pattern": "
<optional with type directory noting the pattern of files inside directory>" }] }
Return: Specifies true if successfully complete or false if fails.
v maestro.loggingUtil.unmonitor(listjson)
Allows the plug-in to remove the specified list of files and directories from being
monitored. This requires the logging service implementation to make one last
extraction from these files and then stop monitoring the files even if new events
are logged in to the files.
Input: jsonData - Specifies the JSON list that contains the details about a
specific role list of information to monitor. The structure of this object is as
follows: { "role": <roleName>", "types": [ { "logtype": "<logtypeName>", "type":
"<file or directory>", "name": "<path with or without a file name>", "pattern":
"<optional with type directory noting the pattern of files inside directory>" }] }
Return: Specifies true if successfully complete or false if fails.
v maestro.loggingUtil.registerPluginLogtype(file)
Allows the plug-in to provide information about custom logtypes if the default
logtype list must be enhanced.
Input: file Specifies the JSON file that contains the definition of the log type.
Return: Specifies true if successfully complete or false if fails.
v maestro.loggingUtil.isImplementationRegistered(ImplName)
Allows plug-ins to know if a specific logging service implementation is
registered on the local virtual machine.
Input: ImplName Specifies the name of the logging service implementation.
Return: Specifies true or false.
v maestro.loggingUtil.getLogTypes()
maestro.loggingUtil.registerImplementation(ImplName, ImplScript)
Allows logging service implementations to retrieve information about the default
logtypes that are available.
Input: None
Return: Specifies the JSON object of all the default logtypes that are available,
represented by the default logtype-config.json file that is provided.

Chapter 7. Managing and deploying virtual patterns

617

Plug-in interaction with the log service

A plug-in must notify the logging service with the list of directories and files to
collect for the log viewer and logging service implementations.
The plug-in notifies the logging service when to start and stop monitoring the
specific files. The plug-in must provide details about the files so the logging service
knows the type of the file (binary or text), and the structure of a single event
inside the file. The plug-in uses the logtype to describe the details of a file to the
logging service so it can properly handle the events.
The plug-in uses the following methods inside the life cycle scripts any time
during the life cycle execution:
v maestro.loggingUtil.monitor(jsonData)
v maestro.loggingUtil.unmonitor(jsonData)
v maestro.loggingUtil.registerPluginLogtype(file)
v maestro.loggingUtil.isImplementationRegistered(ImplName)
The following is an example of how a plug-in interacts with the logging service.
The example illustrates where the default logtypes are used so that the logging
service monitors both specific files and directories for historical purposes.
Inside the example plug-in, the start.py life cycle script first creates a JSON object
that contains a list of files and directories to monitor:
listjson = { "role": "+maestro.role[name]+", "types": [ { "logtype": "SingleLine",
"type": "file", "name": "/opt/plugin/log/instance.log"},
{"logtype": "BinaryFile", "type": "dir", "name": "/opt/plugin/log",
"pattern": "*.errlog"}, {"logtype": "File", "type": "dir",
"name": "/opt/plugin/log}] }

Then, the example plug-in start.py life cycle script notifies the logging service
about the list of files and directories:
maestro.loggingUtil.monitor(listjson)

The logging service monitors these specific files to display in the log viewer and
allow logging service implementations configured to store these for historical
purposes.
Create a log service implementation
The logging service supports custom implementations such as, log backup, logging
collection and analysis service, and software monitoring like Splunk. These
implementations act as the underlying process for a secure information transfer
from the virtual machine and information storage for data review.
The logging service implementation is required to follow these steps:
1. Create a plug-in that contains the logging service implementation that gets
registered with the logging service.
Because the logging service implementation can be used on virtual machines
where the logging service is implemented, the implementation must be a
pattern type plug-in. This allows the logging service implementation to be
properly installed and managed by the plug-in infrastructure.
2. Use the plug-in life cycle script calls to register with the logging service.

618

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The logging plug-in implementation uses its life cycle scripts to register when it
is ready to receive forwarded logging service method calls. The method to do
this registration is maestro.loggingUtil.registerImplementation(ImplName,
ImplScript)
The implementation provides a name, for example, logbackup, so other plug-ins
required to interact with the specific implementation know if that
implementation is active on the virtual machine. Also, this helps the logging
service know that the services are registered. The Python script provided
contains the implementation of the core forwarding methods.
When the implementation is deactivated and does not take any more
forwarded calls from the logging service, the unregistered method is used. The
method to do this unregistration is
maestro.loggingUtil.unregisterImplementation(ImplName).
This again provides the official name of the implementation.
3. Implement the core forwarding methods such as monitor, unmonitor, and
registerPluginLogtype.
Each logging service implementation is required to provide a Python script that
implements the following methods. These methods are automatically called
when the implementation is registered. Any local plug-in on the virtual
machine can call these core methods. The following are the methods to be
implemented:
v monitor(jsonData)
Provides the list of files and directories to be monitored with a logtype. The
logtype defines the details about the binary or text file and what a single
event structure looks like inside the file. If the service cares about the specific
event structure, the logtype defines a generic pattern that indicates the start
and end pattern of a single event for that specific file.
v unmonitor(jsonData)
Provides the list of files and directories to stop monitoring.
v registerPluginLogtype(file)
Provides a file that contains custom logtypes provided by a specific plug-in.
This file explains unique event patterns for the specific plug-in role, for
example:
{"types":[
{
"name": "DB2instance",
"start": "------------------------------------------------------------.*",
"end": "------------------------------------------------------------.*"
},
{
"name": "DB2StandardLog",
"start": "\\d{4}\\-\\d{2}\\-\\d{2}\\-\\d{1,2}\\.\\d{1,2}\\.\\d{1,2}\\.\\d{1,6}.*"
}
]}

The implementation sets up these calls. For example, the logbackup plug-in
creates a registry of files and file patterns required to regularly back up the logs
to an external system.

Chapter 7. Managing and deploying virtual patterns

619

Monitor service for plug-ins:

Plug-ins provide monitoring operations that collect and display deployment
metrics for resource utilization and performance at the virtual machine,
middleware, and application level.
If you are developing your own plug-ins for IBM Cloud Orchestrator, you can
configure and register collectors for plug-in specific metrics at runtime and apply
metadata to define the presentation of the monitoring metrics in the Virtual
Application Console deployment panel.
The following illustration lists the artifacts a plug-in requires to provide
monitoring.
Collector
IBM Cloud Orchestrator monitoring provides specific and built-in collectors, and
generic and typed collectors. These collectors are based on an open,
loosely-coupled, and collector-oriented framework. All collectors are implemented
from the interface com.ibm.maestro.monitor.ICollectorService which includes the
following methods:
// Creates the collector based on the given configuration values.
// @param config
// @return uniqueId for this collector instance or null if the collector could not be created
String create(JSONObject config);
// Returns the metadata for the available metrics from the collector.
// @param uniqueId of the collector instance to query
// @return {"categories":
[{"categoryType":"<ROLE_CATEGORY>"}],
updateInterval": "<secs>":,"<ROLE_CATEGORY>": {<see
IMetricService.getServerMetadat{}>}}
JSONObject getMetadata(String uniqueId);
// @param uniqueId of the collector instance to query
// @param metricType not used in this release and defaults to "all"
// @return {"<ROLE_CATEGORY>":[{"<METRIC_NAME>":"<METRIC_VALUE>"}, ...},
JSONObject getMetrics(String uniqueId);
// @param uniqueId of the collector instance to shutdown void delete(String uniqueId);

IBM Cloud Orchestrator monitoring has three types of collectors that are described
in the following table.
Table 75. Monitoring collector types.. Description of the monitoring collector types available for plug-ins.
Collector

Property

Usage

com.ibm.maestro.monitor.collector.itmosagent Built-in

Collect metrics relevant to CPU, RAM, DISK

and NETWORK of the virtual machine from
the ITM OS Agent.

com.ibm.maestro.monitor.collector.wca

Built-in

Collect metrics relevant to CPU, RAM and

STORAGE of the virtual machine from the
hypervisor.

com.ibm.maestro.monitor.collector.script

Public

Collector for plug-ins that can supply metrics

with shell scripts.

The built-in collectors are dedicated to IBM Cloud Orchestrator monitoring only.
These collectors gather common metrics, like statistics at the virtual machine level.
The public collectors are used by plug-in developers to interact with plug-in
management facilities for metrics collecting.

620

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Registration
To use IBM Cloud Orchestrator monitoring collectors, you must register the
collectors with the plug-in configuration, providing the node, role, metrics, and
collector facilities information.
IBM Cloud Orchestrator provides a Python interface to register the collectors. The
definition of the interface is as follows:
maestro.monitorAgent.register('{
node: String,
role: String,
collector: String,
config: JSONObject
}')

The single parameter,maestro.monitorAgent.register is a JSON string, where:

v node is the name of the server running the collector
v role is the name of the role the collector works for
v collector is the collector type
v config is the required and optional properties of instantiating the typed
collector for the specific node and role. Each type of collectors has its own
config properties.
Table 76. Monitoring collector types.. Description of the monitoring collector types available for plug-ins.
Collector

Configuration properties

com.ibm.maestro.monitor.collector.itmosagent

{
metafile:<full path to metadata json file>,
}

com.ibm.maestro.monitor.collector.wca

{
metafile:<full path to metadata json file>,
"api-version":"3.0"
}

com.ibm.maestro.monitor.collector.script

{
metafile:<full path to metadata json file>,
"executable":"<script to execute>",
"arguments":"<optional arguments>",
"validRC":"<optional - valid return code - defaults to 0>",
"workdir":"<optional - work dir- defaults to java.io- tmpdir>",
"timeout":"<optional - time out (second) - defaults to 5
seconds>",
}

The following code example illustrates the registering script used in the script
collector:
maestro.monitorAgent.register('{
node:${maestro.node},
role:${maestro.role},
collector:com.ibm.maestro.monitor.collector.script,
config:{ metafile:<full path to metadata json file>,
executable:<script to execute>,
arguments:<arguments>,
validRC:<valid return>,
workdir:< work dir >,
timeout:< time out >} }')

Chapter 7. Managing and deploying virtual patterns

621

The registering scripts are typically put into appropriate scripts or directories of
the plug-in lifecycle to ensure that the plug-in is ready to collect metrics. For
example, for the WebSphere Application Server collector, the registering script is
placed under the installApp_post_handlers directory where all scripts are
executed after WebSphere Application Server is running.
Metadata file
The metadata file is referred to in collector registering.
The plug-in provides a JSON formatted file that includes collector metadata
parameters, metric category types that it wants to expose and metadata describing
each exposed metric. The content of the metadata file contains:
v Metadata file version
v array of category names to register (1..n)
v interval time in seconds to poll for updated data
v category unique configuration parameters, like mbeanQuery
v list of metric metadata objects
attributeName - Specifies an attribute from the collector to associate to this
metric
metricName - Specifies a metric name to expose through the monitoring agent
APIs
metricType - Specifies the data type, like range, counter, time, average,
percent, and string
description - (optional) Specifies the string that defines the metric
The format of the metadata file is as follows:
{
"Version" : <metadata file version>,
"Category": [
<array of category names to register (1..n)>
],
"Metadata": [
{
"<category name from Category[]>":{
"updateInterval": <interval time in seconds to poll for update data>
"metricsName": <metric name to expose through monitoring agent APIs>
"metricType": <metric value data type including RANGE",COUNTER,TIME,
AVERAGE,PERCENT",STRING>
} ,
...... ......
]
}
},
...... ......
]
}

User interface presentation

Plug-in metrics are displayed in IBM Cloud Orchestrator Virtual Application
Console Middleware Monitoring tab.
The user interface display is metadata driven. Plug-ins can provide metadata to
describe the metric and category for displaying the metrics, and define the form of
displaying for metrics.

622

IBM Cloud Orchestrator 2.4.0.2: User's Guide

monitoring_ui.json
A plug-in provides the monitoring_ui.json file for metadata. The following code is
an example of the monitoring_ui.json file:
[
{
"category": <category name from Category[] defined in
metric metadata>,
"label": <the content shown on the chart for the category>,
"displays": [
{
"label": <string shown on the chart element for the metric>,
"monitorType": <time and type properties of the metric to display>,
"chartType": <chart type for displaying the metric>,
"metrics": [
{
"attributeName": <metric name defined in the metadata>,
"label": <string shown on the chart element for the metric>,
}
]
}
]
},
...... ......
]
Table 77. Monitor types. Monitor types that are available to define metric data in plug-ins
Monitor types (monitorType)

Description

HistoricalNumber

Metric data in simple number for historical

timeline

HistoricalPercentage

Metric data in percentage for historical

timeline

RealtimeNumber

Metric data in simple number for current

temporality

RealtimePercentage

Metric data in percentage for current

temporality

Table 78. Chart types. Chart types that are available to define metric data in plug-ins.
Chart types (chartType)

Presentation

Lines
StackArea
StackColumn
Pie

The monitoring_ui.json file is located under the plugin directory of a plug-in

project, for example, plugin.com.ibm.was/plugin/monitoring_ui.json. Other JSON
files are also located in this directory, including config.json and
config.meta.json.
Auto scaling
The elastic scaling, or auto scaling, feature in a plug-in uses monitoring.

Chapter 7. Managing and deploying virtual patterns

623

IBM Cloud Orchestrator auto scaling provides the run time with automatic
addition or removal of virtual application and shared services instances based on
instances work load.
You can optionally turn on the auto scaling feature by attaching the scaling policy
to a target application or shared service. The policy is also used to deliver the
scaling requirements to the backend engine. Requirements include trigger event,
trigger time, and instance number, which drive the scaling procedure.
The auto scaling policy can be attached to two kinds of components in IBM Cloud
Orchestrator: a virtual application and a shared service. For the virtual application,
you can explicitly add the scaling policy to one or more components of the
application in IBM Cloud Orchestrators Pattern Builder. For the shared service, the
scaling policy must be described in the application model made by the plug-in
developer if the service asks for the auto scaling capability.
Plug-ins, either for virtual applications or shared services, define the scaling policy,
describe the policy in application model and provide transformers to explain and
add scaling attributes into the topology document when the policy is deployed
with plug-ins. Only if you are using shared services, can the application build
automatically generate the segment of scaling policy in application model. At run
time, the backend auto scaling engine first loads scaling attributes and generates
the rule set for scaling trigger. Then the backend engine computes on the rule set
and decides if the work load reaches a threshold for adding or removing
application or share service instances. The final step of the process is to complete
the request.
Policy elements
The auto scaling policy is composed of elements for different scaling aspects as
follows:
v Trigger Event
Specifies the type of monitoring metrics for the plug-in, including adding and
removing plug-in instances and what thresholds they have.
For each metric in the event definition, there are two thresholds: scale-in
threshold and scale-out threshold. For example, the CPU utilization of virtual
machines that run WebSphere Application Server instances can be the metric for
the trigger event and the thresholds for scale-in and scale-out are 20% and 80%,
then when the value of CPU utilization is higher than the 80%, a new
WebSphere Application Server instance is launched. When the CPU utilization is
below 20%, an existing WebSphere Application Server instance is selected for
removal.
v Trigger Time
Specifies the time it takes to hold an inspecting threshold before performing
scaling operations when the threshold condition is met. For example, if trigger
time is set to 120 seconds at the moment that the CPU utilization is monitored
high than 80%, a timer is started. When the timer reaches 120 seconds, the
scale-out operation is not started. It must be noticed that during the timing, if
the CPU utilization goes out of thresholds, the timer is stopped and waits for
another restarting.
v Instance Number Range
Specifies the total number of instances a plug-in can have at one time or at least
by scale-out or scale-in. When the cluster size of a plug-in reaches the border of
its ranges, no instance is added or removed to or from the cluster, even though

624

IBM Cloud Orchestrator 2.4.0.2: User's Guide

the trigger event is met. To apply the auto scaling policy to a plug-in, ensure
that the scaling policy is defined in the application model that the plug-in is
associated with, which collects user-specific requirement for the scaling
capability. Also ensure that the policy is transformed into the topology
document, which guides the backend engine to inspect trigger event and
perform scaling operations.
Application model
Auto scaling capability is embodied as a policy in the application model. The
application model is used to describe the components, policies, and links in the
virtual applications or shared services. For virtual applications, the model can be
visually displayed and edited with the Pattern Builder.
You can customize your components and policies, including the auto scaling policy,
in the Pattern Builder. There is no tool to visualize shared services in the
application model. Auto scaling can only be customized in the Virtual Application
Console when the service is deployed. The scaling policy that is described in the
application model, for either a virtual application or shared service, follows the
IBM Cloud Orchestrator application model specification. The policy is defined in
the node with a group of attributes.
The three auto scaling elements, trigger event, trigger time and instance number
range, are described in the attribute set. There is no name convention for the
attribute keys, but they must be understood by the plug-in to transfer into a
topology document. The following code is an example of the elements described in
the plug-in:
"model": {
"nodes": [
{
......
},
{
"id": <policy id>
"type":<policy type>
"attributes": {
<No.1 metric id for trigger event>: [
< threshold for scale-in >,
< threshold for scale-out >
],
<No.1 metric for trigger event>: [
< threshold for scale-in >,
< threshold for scale-out >
],
<...... :[...... ,...... ]>
<No.1 metric for trigger event>: [
< threshold for scale-in >,
< threshold for scale-out >
],
<trigger time id>: <trigger time value>
<instance range number id": [
<min number>,
<max number>
],
}
},
{

Chapter 7. Managing and deploying virtual patterns

625

......
}
]
}

The attributes describe the scaling policy in an application model. From above
JSON segment, the Trigger Event can include multiple metrics and thresholds for
one scaling policy. This means that the scaling operations on a plug-in can be
triggered by different condition entries with different metrics. The relationship
among these entries are explicitly explained by plug-in transformer and marked in
the topology document. It is not required to mark them in application model,
except that their label can be used to define the relationship in the user interface.
IBM Cloud Orchestrator requires the metadata be provided in a plug-in to explain
components in the application model for user interface presentation. For scaling
policy, the plug-in can apply proper widget types and data types to the attributes
for Trigger Event, Trigger Time and Instance Number Scope.
Topology document
In the topology document, the scaling is extended to contain the attributes from
auto scaling. The neat scaling contains only attributes of min and max, both of
which typically have the same value. The value indicates the size of a fixed cluster
on the plug-in template.
"vm-templates": [
{
......
scaling :{
"min": <number,
"max": <number>,
}
},
{
......
}
]

When additional attributes such as triggerEvents and triggerTime are included

in the scaling, it evolves to an auto scaling capacity on the cluster. The value of
min and max should not be the same any longer: min for lower limit of
Instance Number Scope and max for the upper limit. The attributes for auto
scaling are illustrated in the following JSON code example:
The attributes for auto scaling in a topology document have the name convention
for keys, which are styled as bold in the previous JSON code example.
IBM Cloud Orchestrator supports multiple trigger events for a scaling operation.
Those events are currently aggregated in two modes: OR and AND. The OR mode
means if only one event happens, is the scaling operation triggered. The AND
operation means if all events happen at the same time, only then is the scaling
operation triggered. Auto scaling depends on monitoring to collect metrics for
inspecting. To ensure that the right metrics are collected, the value of key "metric"
in each trigger event must be consistent with the category and attributeName.
These attributes are defined in the plug-in metadata for monitoring collectors. The
values can be joined by . into metric. For example, CPU.Used" represents the
metric with a category of CPU and an attributeName of Used.
The transformer provided by the plug-in must define attributes of the scaling
policy in the application model and map them to the named attributes in the

626

IBM Cloud Orchestrator 2.4.0.2: User's Guide

topology document. The Trigger Event, Trigger Time, and Instance Number Scope
autoscaling elements correspond to "triggerEvents", "triggerTime", and "min"&"
max".
Pattern type packaging reference:
The pattern types are a collection of plug-ins. The plug-ins contain the
components, policies and links of the virtual application pattern. This topic
explains the packaging of the plug-ins that create the virtual application pattern
type.
Virtual application pattern types are shipped with IBM Cloud Orchestrator or they
are purchasable at the IBM PureSystems Centre.
The associated plug-in files that are associated with a pattern type are as follows:
v {ptype}.tgz file
v plugins/set of {plugin}.tgz files
v files/set of {name} files
The {ptype}.tgz file is required and must contain the patterntype.json file. The
{ptype}.tgz file might also contain the license and localized messages. For
example, the patterntype.json file for the IBM Web Application Pattern (not
released with the product) is as follows:
{
"name":"NAME",
"shortname":"webapp",
"version":"2.0.0.0",
"description":"DESCRIPTION",
"prereqs":{
"foundation":"*"
},
"license":{
"pid":"5725D57",
"type":"PVU"
}
}

A pattern type defines a logical collection of plug-ins, but not the members. The
members (plug-ins) define their associations with pattern types in the config.json
file. Therefore, pattern types are dynamic collections and can be extended by third
parties. For example, the config.json file for the DB2 plug-in (not released with
the product) is as follows:
{
"name":"db2",
"version":"2.0.0.0",
"files":[
"db2/db2_wse_en-9.7.0.3a-linuxx64-20110330.tgz",
"optim/dsadm223_iwd_20110420_1600_win.zip",
"optim/dsdev221_iwd_20110421_1200_win.zip",
"optim/com.ibm.optim.database.administrator.pek_2.2.jar",
"optim/com.ibm.optim.development.studio.pek_2.2.jar"
],
"patterntypes":{
"primary":{
"dbaas":"1.0"
},
"secondary":[
{
"webapp":"2.0"
}
Chapter 7. Managing and deploying virtual patterns

627

]
},
"packages":{
"DB2":[
{
"persistent":true,
"requires":{
"arch":"x86_64"
},
"parts":[
{
"part":"parts/db2-9.7.0.3.tgz",
"parms":{
"installDir":"/opt/ibm/db2/V9.7"
}
},
{
"part":"parts/db2.scripts.tgz"
}
]
}
]
}
}

Samples:
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the IBM Cloud Orchestrator catalog and used as
components, links and policies for virtual applications.
Plug-ins and pattern types are built and packaged using Apache Ant. The Plug-in
Development Kit (PDK) provides Ant build (.xml) files for this purpose. These
build files can run from the command line or from within Eclipse. Other
development environments can work, but only command line and Eclipse are
supported.
The Samples are included with the Plug-in Development Kit (PDK). Download the
PDK to get started with Samples. You can also download the PDK from the IBM
Cloud Orchestrator user interface Welcome page.
Attention: You must enable the PDK license before you can use the PDK. A
dialogue box displays during download to assist you with the license acceptance
process.
Sample pattern types and plug-ins
There are four projects in the form of plug-ins included in the PDK zip package.
These plug-ins show how to design an application model, configuration, virtual
machine template, and Python scripts of a plug-in.
plugin.com.ibm.sample.hellocenter: The plug-in project of HCenter plug-in
In this plug-in, you can learn how to write the lifecycle scripts, such as install,
configure, start, and stop for middleware like HelloCenter. You can use the
following scripts:
v install.py: Downloads artifacts from storehouse and installs the middleware. If
you want to download and extend the .tgz installation file from the storage
server, use the function downloadx instead.

628

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v configure.py: Downloads the artifacts uploaded by the plug-in and configures

the middleware, and opens the firewall to accept customer requests. Export its
IP address.
v start.py: Starts the HelloCenter server and changes the role status to Running.
v stop.py: Stops the HelloCenter server.
You can also access the maestro module and use the logger to log your messages.
For more details about the maestro module and the advanced log such as
maestro.trace_call, see the topic, Plug-in development guide.
plugin.com.ibm.sample.hello: The plug-in project of Hello plug-in
This plug-in accesses the HelloCenter and must work with the HClink plug-in.
This plug-in contains the following scripts:
v configure.py: Logs the sender information.
v start.py: Changes the role status to Running.
plugin.com.ibm.sample.hclink: The plug-in project of HClink plug-in
This plug-in links Hello and HelloCenter and is installed along with the Hello
plug-in in the same virtual machine. The following script is included in this
plug-in:
v changed.py: This script runs only after the Hello and HelloCenter plug-in roles
are in the Running state.
This script checks to see if the depended role HelloCenter exists and reads the
transferred parameters from HelloCenter, which is exported in the HelloCenter
configure.py script. The change.py script uses the HelloCenter IP address to
access HelloCenter and prints the returned messages. This script also shows how
to localize your messages.
With Hello, HelloCenter, and HClink plug-ins, you can learn the following tasks:
v How to transfer parameters between two plug-ins.
v How to make two or more plug-ins work together.
There are sample application model and configuration, virtual machine template,
and virtual machine template configurations included with the plug-ins. You can
design your artifacts based on the sample application model, configuration, virtual
machine template and virtual machine configurations, rather than creating them
from scratch. For more details, see the topic, Plug-in development guide.
patterntypetest.hello: The pattern type project of patterntypetest.hello
v The patterntype.json file provides a sample on how to configure your pattern
type.
v The build.patterntype.xml file is used to build the pattern type into a package.
Attention: Before running this script, you must run the build.xml in the
plugin.depends project to build all plug-ins in your workspace.
v The license folder includes all license documents for all supported languages.
v The locales folder stores all translated files for all supported languages for the
message.json file.

Chapter 7. Managing and deploying virtual patterns

629

Sample: Setting up the plug-in development environment:

Set up the environment for the plug-in Samples.
Before you begin
The following products are required before setting up the environment:
v Eclipse V3.6.2, 32-bit. The Java Platform, Enterprise Edition (Java EE) version is
recommended.
Eclipse is not required, but if you use it, use this version.
If you use Eclipse, you can use the Ant that comes with it. Do not install Ant
separately. Ant is located in the Eclipse installation directory at
eclipse/plugins/org.apache.ant_1.*.

v Java Standard Edition (SE) 6, 32-bit

v Apache Ant, 1.7 or later
About this task
This task is required before using the plug-in development Samples. To set up your
environment, complete the following steps:
Procedure
Import the sample source code and build the hello pattern type binary package.
1. Create a workspace called iwd-pdk-workspace in Eclipse.
2. Download the pdk.sample_<version>.zip to a file directory.
3. Click File > Import > General > Existing Projects into Workspace.
4. Click Select archive file and click Browse.... Select the iwd-pdk-workspace
directory where you downloaded the pdk-<version>.zip file.
5. Select the plugin.depends project and the four sample projects.
After the import is done, the following projects are located in your workspace:
v patterntypetest.hello
v plugin.com.ibm.sample.hclink
v plugin.com.ibm.sample.hello
v plugin.com.ibm.sample.hellocenter
v plugin.depends
These projects are used in the next steps of end to end process of using custom
developed plug-ins.
Results
You have set up your plug-in development environment.
What to do next
Develop a plug-in and pattern type.

630

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Sample: Developing a plug-in and pattern type with the Eclipse Framework:
This topic is an example of how to create a plug-in and pattern type using the
Eclipse Framework.
Before you begin
Download and install the Plug-in Development Kit (PDK) and set up the
development environment.
About this task
Procedure
1. Go to the workspace that you created in the topic, Setting up the samples
environment section.
2. Build a single plug-in.
3. In the plugin.depends project, run the build.xml Ant script. To run the Ant
script, right-click on the file and select Run As > Ant Build. The plug-in build
process starts.
When the build process completes, refresh the project and a folder named
export displays. All of the build artifacts are listed in the export folder.
The plug-in package is in the root of export folder.
4. Build all plug-ins in the workspace. Select the build.xml file in the root of the
plugin.depends project. Right-click and select Run As > Ant Build. The plug-in
build process starts.
When the build process completes, refresh the project. A folder named image
displays in the sub-folder plug-ins, where all of the built plug-in packages are
located.
5. Build a single pattern type. Before this step, you must successfully complete
Step 2.
Select the build.patterntype.xml file in the root of the patterntypetest.hello
project. Right-click and select Run As > Ant Build. The pattern type build
process starts.
When the build process completes, refresh the project. A folder named export
displays where all the build artifacts are listed. The pattern type package is in
the root of export folder.
6. Navigate to the root of the export folder. The hello-2.0.0.0.tgz pattern type
binary file is located here. The sample pattern type patterntypetest.hello release
package includes three plug-ins:
v HCenter plug-in: This plug-in operates a simple message center middleware
named HelloCenter. HelloCenter opens port 4000 and listens to client
requests, and generates and returns greeting messages.
v Hello plug-in: This plug-in is a client component of HelloCenter. It sends a
request with the message sender identity to the Hello Center and tries to get
the returned greeting message and display the message on the console.
v HClink: This link plug-in from Hello to HCenter specifies the receiver name
of greeting message.
Results
You have created a plug-in that can be imported into the IBM Cloud Orchestrator
catalog.
Chapter 7. Managing and deploying virtual patterns

631

What to do next
Import the plug-in into IBM Cloud Orchestrator.
Sample: Import a plug-in and pattern type into IBM Cloud Orchestrator:
This topic is an example of how to import your sample plug-in into IBM Cloud
Orchestrator
Before you begin
Develop the plug-in.
About this task
Procedure
Import the pattern type hello-2.0.0.0.tgz and try sample plug-ins. The steps for
this task are based on a scenario where you have installed and configured IBM
Cloud Orchestrator.
1. Import pattern type patterntypetest.hello.
a. Log in into IBM Cloud Orchestrator as administrator or as a user with
permission to create a new pattern type.
b. Click PATTERNS > Deployer Configuration > Pattern Types.
c. Click the New icon (+).
The Install a pattern type window displays.
d. On the Local tab, click Browse.
Select the hello-2.0.0.0.tgz file. When the installation process completes,
the pattern type, patterntypetest.hello, is displayed in the Pattern Types
palette.
e. Select patterntypetest.hello pattern type from the drop down list
The pattern type details display on the right.
f. Click Accept to accept the license. Click Enable to enable this pattern type.
Results
You have imported a plug-in and pattern type into IBM Cloud Orchestrator
catalog.
What to do next
Create an application that can be deployed to IBM Cloud Orchestrator.
Sample: Creating an application with the patterntypetest.hello plug-in:
In this Samples topic, you use the patterntypetest.hello plug-in to create an
application that is deployed to IBM Cloud Orchestrator.
Before you begin
Set up your development environment and develop a plug-in and pattern type.

632

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

To create an application with the plug-ins, complete the following steps:
Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The
Virtual Application Patterns palette displays. Ensure that the
patterntypetest.hello 2.0 is selected.
2. Select the patterntypetest.hello 2.0 from the patterns list.
3. Click the New icon (+) at the top of the page. The Create Application dialogue
window displays.
4. Select the type of application to create.
5. Click Start Building. The Pattern Builder displays in a new window.
6. Select the Diagram tab.
7. In the Other Components located in the left palette, drag the Hello and
HelloCenter components into the middle section of the canvas. Name the
application to the right in the Virtual Application palette.
8. Select the List View tab (located next to the Diagram tab).
9. Create the sample_userlist.json file with the following content
["Mike","Alice","Joe"].
10. Click the HelloCenter component. In the right attributes view, type sample in
the Hello Center Name attribute field. Upload the created
sample_userlist.json file in the Registered User List.
11. In the Diagram tab, click the Hello component. In the right attributes view,
type one of the following: "Mike","Alice","Joe".
12. Link Hello to HelloCenter. Click the link and type any name in the receiver of
greeting message attribute field.
13. To review all of the settings configured in the previous steps, click the List
View tab on the left palette.
14. Click Save and return to the Virtual Application Patterns page.
15. Refresh the Virtual Application Patterns page to display the new application.
16.

17.
18.
19.
20.

The application displays in the list located on the left.

Select the application and click the Deploy icon in the top right palette.
The Deploy Virtual Application window displays. Complete the settings
information and click OK. For more information about deploying virtual
applications, see the topic, Deploying virtual applications.
When the deployment is complete, the status icon turns green.
To view the deployed application, click PATTERNS > Instances > Virtual
Application Instances. The Virtual Application Instances window displays.
Select the virtual_application_instance. The details view displays to the right.
Find the row of Hello_Plugin-HVM-XXXX, where XXXX is a set of digits in the
virtual machine list.
Click the log to the right of Running. The Log page displays.

21. In this log page, from the root, go to IWD Agent > "../logs/Hello_PluginHVM.XXXX.hello" > console.log.
The following information is provided:

Chapter 7. Managing and deploying virtual patterns

633

[2011-06-30 04:10:49,592] Hello/HCenter/changed.py 47121262922944 pid=16205

INFO Send the request to get a greeting message from Mike to Alice
[2011-06-30 04:10:49,859] Hello/HCenter/changed.py 47121262922944 pid=16205
INFO Receive the message from hello center: Mike, a kind greeting message
from Alice has been sent out

Results
You have created a virtual application and deployed it to IBM Cloud Orchestrator.
What to do next
Monitor the virtual application instance.
Sample: Creating a plug-in project from the command line:
This topic is an example of how to create a plug-in project using command-line
tools.
Before you begin
1. Open the command-line tool.
2. cd to the plugin.depends project directory in your workspace.
3. Set the ANT_HOME environment variable. You can use Ant in your Eclipse
installation at eclipse/plugins/org.apache.ant_1.7*. You can also invoke this Ant
script from Eclipse. To do this, right-click create.plugin.project.xml in the
plugin.depends project. Select Run As > Ant Build. Click the Main tab. In the
argument section, type the various -Dproject.name=jp1 values provided in this
sample.
About this task
Continue with this task by completing the following steps:
Procedure
1. Create a template plug-in project as follows:
ant -Dproject.name=tp1 -Dplugin.name=a.b.c.template -f create.plugin.project.xml

project.name property is optional and if it is not specified, it will default to the

value of the plugin.name.
2. Create a Java plug-in project as follows:
a. Create a Java plug-in project that contains no package name:
(.java assumed on java classname)
ant -Dproject.name=jp1 -Dplugin.name=a.b.c.java -Djava.classname=MyPlugin
-f create.plugin.project.xml

b. Create a Java plug-in project that contains a package name:

ant -Dproject.name=jp2 -Dplugin.name=a.b.c.java -Djava.classname=a.b.c.MyPlugin
-f create.plugin.project.xml

3. Verify that the command is successful. Import the newly created projects into
your workspace.
To build the plug-in projects, for example, jp1, you can find build.plugin.xml
in project jp1. Right-click build.plugin.xml and issue Run As > Ant Build

634

IBM Cloud Orchestrator 2.4.0.2: User's Guide

with the goal clean, publish selected. The equivalent Ant command is to issue
the following command in the project jp1 directory:
ant f build.plugin.xml clean publish

The plug-in a.b.c.java-<version>.tgz is created in the export directory.

Sample: Building a single plug-in and pattern type with the command-line tools:
This topic is an example of how to create a plug-in and pattern type using
command-line tools.
Before you begin
This task assumes that you have the following installed:
v The Ant build environment version 1.7.1 or higher.
v A command-line environment like Linux console or Windows command line
interface.
v A message format tool such as msgfmt (Linux) or msgfmt.exe (Windows). Add
the tool folder into the system path to ensure that you can start the tool without
the full path.
Procedure
1. Go to the workspace that you created in the topic, Setting up the samples
environment section.
2. Navigate to the root folder of target plug-in project.
3. Type this command to build a single plug-in:
<ant command path> -f build.plugin.xml

The building information displays in the console.

4. Go to the export folder of the plug-in project. This folder is generated by step
3. Locate the plug-in package, which is a .tgz file.
5. Navigate to the root of the plugin.depends project.
6. Type the following command to build all plug-ins in this workspace:
<ant command path> -f build.xml

This command builds the plug-ins in this workspace one at a time. After the
script starts, go to the image/plugins folder of the plugin.depends project to
check all of the built plug-in packages.
7. Navigate to the root of the pattern type project, patterntypetest.hello, and type
the following command:
<ant command path> -f build.patterntype.xml

After the script starts, go to the root of the export folder of the
patterntypetest.hello project to check the built pattern type package, which is a
.tgz file.

Chapter 7. Managing and deploying virtual patterns

635

Deploying virtual applications

A virtual application is an application that has been optimized to run on a virtual
environment. The application software and middleware is located inside a virtual
machine in a manner that maximizes the performance of the application. By
keeping the system software to a minimal set of packages required to support the
application, the maintenance and administration of the virtual application is
reduced. The virtual application pattern is the first step to building a virtual
application.

About this task

The virtual application template and a virtual application pattern are the first steps to
building a virtual application.
You can use virtual application template that is associated with a virtual
application pattern to start building an application.
The virtual application pattern is a collection of plug-ins. The plug-ins in a virtual
application pattern define a complete set of platform resources to fulfill a business
need, including web applications, databases, user registries, and more. These
components or plug-ins can be added to a virtual application pattern using the
Pattern Builder or they might already exist in the pattern.
A deployed virtual application is called a virtual application instance.

Procedure
1. Deploy a virtual application using one of the following methods:
v From a virtual application pattern
v From a virtual application template
2. Secure a virtual application.
3. Monitor and administer virtual applications.

Deploying virtual application patterns

After you create a virtual application, you can provision and deploy it on the
infrastructure cloud. Each deployment of a virtual application represents a running
virtual application instance on the cloud infrastructure. You can deploy a given
virtual application multiple times. When you deploy your virtual application you
can also configure Secure Shell (SSH) key-based access.

Before you begin

Set the deploy base image by performing the following steps:
1. Set the base image as the default. Click PATTERNS > Deployer Configuration
> Default Deploy Settings
. The Settings for Default Deploy window is
displayed.
2. Click
Change
and select an image.
3. Click Update to save your changes.
Create a virtual application.

636

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

When a virtual application is deployed, the Pattern Builder allocates necessary
resources, such as virtual machines and block storage on the cloud infrastructure,
and deploys, configures, and starts the virtual application components in the
cloud.
Policies that are associated with the virtual application typically influence how
cloud infrastructure resources and virtual application pattern components are
allocated for a given deployment. For example, a single virtual machine running
the web application is provisioned when a web application component is
deployed. However, a scaling policy that is associated with a web application
results in multiple virtual machines, equal to the cluster size that you specify for
the scaling policy, provisioned for the web application, an elastic load balancer
cloud component that is used for routing HTTP requests, and a set of WebSphere
Extreme Scale application components that facilitate session replication across the
cluster members of the web application.
The time it takes to deploy a virtual application depends on several factors, such
as the size of the virtual application pattern parts and the inter-dependencies of
parts in the application definition, network usage, storage usage, and the
provisioning speed of the virtual machine on the cloud infrastructure.
You can add SSH key-based access to your workload virtual machine when
deploying the virtual application. This type of security provides better protection
than password-based access.
To deploy a virtual application pattern:

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Patterns. The Virtual
Application Patterns palette displays.
2. From the left panel of the Virtual Application Patterns palette, select the
virtual_application that you want to deploy.
3. Click the Deploy icon to deploy the virtual application. The Deploy Virtual
Application dialogue box displays.
4. Complete the Target environment profile fields.
These settings provide deployment configuration information, like virtual
machine names, IP address assignment, and cloud groups. Deploying virtual
applications with environment profiles enables deployments across tiers from a
single application.
a. Select the IP type filter, IPv4 or IPv6, in the Filter by IP type field.
b. Select the Filter by profile type from the drop down menu.
c. Select the Profile from the drop down menu.
d. Select theCloud group from the drop down menu.
e. Select the IP group from the drop down menu.
5. Click Advanced to set the SSH public key.
a. Enter an SSH public key in the SSH Key field. You can use a text editor to
open your public key file and, copy and paste the key into the SSH Key
field.

Chapter 7. Managing and deploying virtual patterns

637

Important: Do not use cat / less to copy and paste from the user interface.
This type of cut and paste introduces spaces to the key and you cannot gain
access to the virtual machine.
If you do not want to use an existing SSH public key, you can generate one
as described in the next step.
a. Click Generate to generate the key. The SSH key is automatically generated
in the SSH Key field. Select Click here to download the file containing the
private key->Save to save the private key file. Save the file to a secure
location and you can name the key. The default name is id_rsa.txt. The
system does not keep a copy of the private key. If you do not download the
private key, you cannot gain access to the virtual machine, unless you
generate a new key pair again using user interface. You can also copy and
paste the public key, save the key, and reuse the same key pair for another
deployment. When you have the private key, make sure that it has the
correct permissions (chmod 0400 id_rsa.txt). By default, the ssh client does
not use a private key file with wide open permission.
6. Click OK. A message displays at the top of the Pattern Builder confirming that
the virtual application is in the deployment process. You can also check the
status of the deployment from this message.
Attention: You cannot modify a virtual application after you deploy it. You
must stop the deployed virtual application before you can change it.
When the virtual application is deployed, to view the virtual instance, click
PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays.
Note: If the deployment process is stopped and in the Virtual Application
Instances window the flavor error message is displayed, you must create a
flavor with memory, vCPUs, and storage values equal to or greater than the
requirements of the virtual machines that you are deploying. For information
about creating flavors, see Managing flavors on page 100.
After you created the new flavor, delete the virtual application instance and
redeploy the virtual application pattern. .
7. View the details of the deployed virtual application in the Virtual Application
Instances palette. The details include a list of virtual machines provisioned on
the cloud infrastructure for that deployment, the IP address, virtual machine
status, and role status. Role is a unit of function that is performed by the virtual
application middleware on a virtual machine.
The status values are listed in the following table:
Table 79. Possible status values for a deployed virtual application

638

Status

Deployment description

Virtual machine description

LAUNCHING

The virtual application is

being deployed.

The virtual machine is being

provisioned on the
infrastructure cloud.

INSTALLING

Not applicable

The components of the

virtual application are being
provisioned on the virtual
machine.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 79. Possible status values for a deployed virtual application (continued)
Status

Deployment description

Virtual machine description

RUNNING

Resources are being

provisioned on the
infrastructure cloud.

The components of the

virtual application are
running on the virtual
machine and can be
accessed.

TERMINATED

The deployment process is

stopped.

The virtual machine is

stopped.

FAILED

The deployment process

could not be started due to
either the application
configuration or a failure
occurring in the
infrastructure cloud.

The virtual machine did not

start successfully.

You can also view the virtual machine role health status information. For
example, a red check mark is located on the green status arrow when the CPU
is critical on the virtual machine.
Click Endpoint to view the endpoint information for a given role. For a
deployment with DB2 you can have more than one endpoint, for example, an
endpoint for application developer one for database administrator.

Results
Your virtual application instance is successfully deployed and started. To stop the
virtual application instance, select the application from the list, and click Stop.
To redeploy a virtual application, select the virtual application from the Virtual
Application Patterns palette, and click the Deploy icon in the Pattern Builder.
To remove a stopped application, select it from the Virtual Application Patterns
palette, and click Delete.

What to do next
After you deploy your virtual application, you can use the IP address of the virtual
machines to access the application artifacts. For example:
To gain access to your virtual machine after deployment type:
ssh -i id_rsa.txt virtuser@<your_workload_ip>

For SCP:
scp -i id_rsa.txt myfiles.txt virtuser@<your_workload_ip>

You can now log in to your virtual machine without a password.

To gain root access:
sudo su -

To run a command with root access:

sudo /sbin/ifconfig

Chapter 7. Managing and deploying virtual patterns

639

You can view and monitor statistics for your deployed virtual machines and
download and view the log files from the user interface. For more information, see
Monitoring virtual application instances on page 650.

Deploying virtual application templates

You can directly deploy a virtual application template from the IBM Cloud
Orchestrator catalog. Virtual application templates that are associated with pattern
types are shipped with the product or you can create one.

Before you begin

You must have a virtual application template created or use a preinstalled virtual
application template.

About this task

You can use the Pattern Builder to allocates necessary components, links and
policies to application template.
To deploy a virtual application template:

Procedure
1. Click PATTERNS > Pattern Design > Virtual Application Templates. The
Virtual Application Templates palette displays.
2. From the left panel of the Virtual Application Templates palette, select the
virtual_application_template that you want to deploy.
3. Click the Deploy icon. The Deploy Virtual Application dialogue box displays.
4. Complete the Target environment profile fields.
These settings provide deployment configuration information, like virtual
machine names, IP address assignment, and cloud groups. Deploying virtual
applications with environment profiles enables deployments across tiers from a
single application.
a. Select the IP type filter, IPv4 or IPv6, in the Filter by IP type field.
b. Select the Filter by profile type from the drop down menu.
c. Select the Profile from the drop down menu.
d. Select the Cloud group from the drop down menu.
e. Select the IP group from the drop down menu.
5. Click Advanced to set the SSH public key.
a. Enter an SSH public key in the SSH Key field. You can use a text editor to
open your public key file and, copy and paste the key into the SSH Key
field.
Important: Do not use cat / less to copy and paste from the user interface.
This type of cut and paste introduces spaces to the key and you cannot gain
access to the virtual machine.
If you do not want to use an existing SSH public key, you can generate one
as described in the next step.
a. Click Generate to generate the key. The SSH key is automatically generated
in the SSH Key field. Select Click here to download the file containing the
private key->Save to save the private key file. Save the file to a secure
location and you can name the key. The default name is id_rsa.txt. The
system does not keep a copy of the private key. If you do not download the
private key, you cannot gain access to the virtual machine, unless you

640

IBM Cloud Orchestrator 2.4.0.2: User's Guide

generate a new key pair again using user interface. You can also copy and
paste the public key, save the key, and reuse the same key pair for another
deployment. When you have the private key, make sure that it has the
correct permissions (chmod 0400 id_rsa.txt). By default, the ssh client does
not use a private key file with wide open permission.
6. Click OK. A message displays at the top of the Pattern Builder confirming that
the virtual application is in the deployment process. You can also check the
status of the deployment from this message.
Attention: You cannot modify a virtual application after you deploy it. You
must stop the deployed virtual application before you can change it.
When the virtual application is deployed, to view the virtual instance, click
PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays.
7. View the details of the deployed virtual application in the Virtual Application
Instances palette. The details include a list of virtual machines provisioned on
the cloud infrastructure for that deployment, the IP address, virtual machine
status, and role status. Role is a unit of function that is performed by the virtual
application middleware on a virtual machine.
The status values are listed in the following table:
Table 80. Possible status values for a deployed virtual application
Status

Deployment description

Virtual machine description

LAUNCHING

The virtual application is

being deployed.

The virtual machine is being

provisioned on the
infrastructure cloud.

INSTALLING

Not applicable

The components of the

virtual application are being
provisioned on the virtual
machine.

RUNNING

Resources are being

provisioned on the
infrastructure cloud.

The components of the

virtual application are
running on the virtual
machine and can be
accessed.

TERMINATED

The deployment process is

stopped.

The virtual machine is

stopped.

FAILED

The deployment process

could not be started due to
either the application
configuration or a failure
occurring in the
infrastructure cloud.

The virtual machine did not

start successfully.

You can also view the virtual machine role health status information. For
example, a red check mark is located on the green status arrow when the CPU
is critical on the virtual machine.
Click Endpoint to view the endpoint information for a given role. For a
deployment with DB2 you can have more than one endpoint, for example, an
endpoint for application developer one for database administrator.

Chapter 7. Managing and deploying virtual patterns

641

Results
Your virtual application instance is successfully deployed and started. To stop the
virtual application instance, select the application from the list, and click Stop.
To redeploy a virtual application, select the virtual application from the Virtual
Application Patterns palette, and click the Deploy icon in the Pattern Builder.
To remove a stopped application, select it from the Virtual Application Patterns
palette, and click Delete.

What to do next
After you deploy your virtual application, you can use the IP address of the virtual
machines to access the application artifacts. For example:
To gain access to your virtual machine after deployment type:
ssh -i id_rsa.txt virtuser@<your_workload_ip>

For SCP:
scp -i id_rsa.txt myfiles.txt virtuser@<your_workload_ip>

You can now log in to your virtual machine without a password.

To gain root access:
sudo su -

To run a command with root access:

sudo /sbin/ifconfig

You can view and monitor statistics for your deployed virtual machines and
download and view the log files from the user interface. For more information, see
Monitoring virtual application instances on page 650.

Securing virtual applications

This topic introduces the security levels available to virtual applications. You can
secure the virtual application at the component level or as a virtual application
instance.

About this task

The following are levels of security used in virtual applications:

Procedure
v User roles in IBM Cloud Orchestrator on page 255. Review the user roles that
apply to creating a virtual application pattern.
v Secure Socket Layer (SSL).
v Configuring Secure Shell (SSH) key-based access during application deployment.
v Configuring SSH key-based access in the user interface on page 646.
v LTPA keys.

642

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Securing virtual application instances with SSL:

The security of a virtual application instance can be managed with Secure Sockets
Layer (SSL) certificates.
About this task
You can manage personal and application SSL certificates in WebSphere
Application Server keystore and truststore for secure inbound authentication and
communication. To ensure SSL communication, servers require a personal
certificate that is either self-signed, chained or signed by an external certificate
authority (CA).
IBM Cloud Orchestrator supports the use of one certificate per application
deployment. By default, your deployed application has a uniquely generated
certificate signed by the internal WebSphere root signer certificate. The certificate is
valid for one year, but can be renewed at any time. The IBM Cloud Orchestrator
also supports replacing this default certificate with a certificate signed by an
external CA.
The SSL functionality is a simplified security layer on top of, and subset of, what is
provided by WebSphere Application Server.
Procedure
1. Click PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays.
2. Select the WebSphere Application Server virtual application instance. The
virtual application instance details display.
3. Click the Manage icon.
4. Select the Operations tab. The Operations palette opens.
5. Select the WebSphere Application Server application. The deployment
operations palette displays the operations on the right. Now you can manage
the SSL certificates.
6. Renew the WebSphere Application Server application SSL certificate. To renew
the default application certificate, expand Renew WebSphere Application
Server application SSL certificate to display the deployment operations
palette. Click Submit. The operation status displays in the Operation Execution
Results palette. When the operation displays as successful the validity of the
certificate is extended. You might need to wait a short time for the updated
certificate to propagate to all of the application servers if your deployment has
multiple WebSphere Application Server nodes.
Important: This operation is only possible if you have not previously replaced
the default application certificate with a CA-signed certificate; it otherwise fails.
7. Configure a CA-signed certificate.
a. Create a signer request. To replace the default application certificate with
one signed by an external CA, you must first create a personal certificate
request. To create a persona certificate request, expand Create CA signer in
the deployment operations palette and complete the fields. The common
name (CN) matches the domain name that is used for the application. Click
Submit.

Chapter 7. Managing and deploying virtual patterns

643

When the operation is complete, the status shows as successful in the

Operation Execution Results palette. A link is available in the Return Value
column to download the newly generated signer request file. You must
provide this file to the CA for signing.
Important: IBM Cloud Orchestrator supports only one pending certificate
signer request. If a new request is created before accepting the CA-signed
certificate corresponding to a previous request, that certificate is no longer
accepted.
b. Upload a CA-signer request.
This step is used to import a CA-signed certificate. The signed certificate
must correspond to the last signer request created for the application
deployment in question. Once imported, the certificate replaces the
previously configured application certificate, whether that is the default
WebSphere signed certificate or a previously imported CA-signed certificate.
To import, click Browse to locate the certificate file. The certificate file must
be in base64-encoded PEM form. A progress bar shows that the file is
uploading. When the upload completes, click Submit to complete the
operation. Success is indicated in the Operation Execution Results palette.
8. Manage the truststore certificate.
a. Import a WebSphere Application Server truststore certificate. Use these
instructions to import external signer certificates. The certificate file must be
in base64-encoded PEM form. When uploading a certificate to import, a
unique alias must be specified to identify the certificate. Make sure to
record the chosen alias since there is not currently a way to list previously
imported certificates. There is no limitation on the number of certificates
that can be imported and reside in the truststore concurrently.
For applications that are deployed on IBM Cloud Orchestrator to securely
connect to external services over SSL the appropriate signer (public)
certificates must reside in the WebSphere Application Server truststore.
b. Remove a WebSphere Application Server truststore certificate. You can
remove previously imported signer certificates from the truststore. You must
provide the alias given when the certificate was imported.
9. Export a certificate. You can also extract and export the signer part of the
current application SSL certificate or the WebSphere root signer certificate from
the deployment operations screen. Expand Export certificates and select a
certificate that you want to export from the drop-down menu (Application
certificate or WebSphere Application Server root signer certificate), and click
Submit. When the certificate is ready, the operation status displays as
successful in the Operation Execution Results palette. You can download the
file using the link in the Return Value column. The certificate file is a
base64-encoded PEM form.
Results
You have performed various tasks to manage the SSL truststore and keystore
certificates.

644

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Configuring SSH key-based access during application deployment:

You can add Secure Shell (SSH) key-based access to your workload virtual machine
when deploying the virtual application pattern. This type of security provides
better protection than password-based access.
Before you begin
You must create the virtual application template and pattern before you can apply
SSH.
About this task
When deploying a virtual application pattern, you can configure an RSA key pair
to enable SSH key based access to the virtual machines. You can either provide
your own externally-generated public key or allow the system to generate a new
key pair for you.
Procedure
1. Select the Advanced check box to add the SSH protocol key in the Deploy
Virtual Application dialog box.
2. Enter your SSH public key in the SSH Key field. You can use a text editor to
open your public key file and, copy and paste the key into the SSH Key field.
The key string must be in the public key format used in the OpenSSH
authorized_keys file.
Important: Do not copy the key from the console output of the Linux
command more. This can introduce line breaks into the key that might render it
invalid.
If you do not want to use an existing SSH public key, you can generate one as
described in the next step.
a. Click Generate to generate the key. The SSH public key is automatically
populated in the SSH Key field. Select Click here to download the file
containing the corresponding private key->Save to save the private key
file. Save the file to a secure location and you can name the key. The default
name is id_rsa.
Attention: If you are using Windows, the downloaded file might be
renamed to id_rsa.txt.
The system does not keep a copy of the private key. If you do not
download the private key, you cannot gain access to the virtual machine,
unless you configure a new public key through the deployment
management user interface.
The generated key pair can be reused for subsequent deployments, which
means that your SSH client does not have to be reconfigured with a new
private each time. Copy and save the generated public key from the SSH
Key field and paste it into the same field the next time you deploy a virtual
application.
The generated id_rsa private key file is in OpenSSH format and can be
used with OpenSSH (the standard Linux SSH implementation) and is
compatible with SSH clients. To use the key with other clients, the key
might need to be converted to a different format. If this cannot be done, it is
recommended that you generate a key pair separately.

Chapter 7. Managing and deploying virtual patterns

645

Important: It is highly recommended that you save id_rsa in a secure

location.
b. Click OK to continue to deploy your virtual application with SSH enabled.
A message displays at the top of the Pattern Builder confirming that the
virtual application is in the deployment process. You can also check the
status of the deployment from this message.
c. To log in to the operating system of your virtual application virtual
machines, find the appropriate IP address from the Virtual Application
Instance details palette and specify the user ID, virtuser, along with the
private key. When you are connected, the user ID can be used for root-level
access without requiring a password.
Remember: To use the private key with the OpenSSH client (Linux SSH
command), make sure that it has the correct permissions (chmod 0400
id_rsa). By default the SSH client rejects a private key file with less
restrictive permissions.
Results
The virtual application pattern for which you are deploying has SSH key-based
access enabled.
Attention: You can also generate an SSH key when you configure shared services.
See the topic, Working with shared services, for more information.
Configuring SSH key-based access in the user interface:
You can update a Secure Shell (SSH) key-based access configuration for a deployed
virtual instance by accessing the Operations tab in the Virtual Application Console
of IBM Cloud Orchestrator.
Before you begin
You must have admin role to complete this task.
You must also create the virtual application template and pattern before you can
apply SSH.
About this task
When deploying a virtual application pattern, you can configure an RSA key pair
to enable SSH key based access to the virtual machines. You can either provide
your own externally-generated public key or allow the system to generate a new
key pair for you.
Procedure
1. Click PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays with the virtual application instances
listed.
2. Select a virtual_application_instance. The details display to the right.
3. Click the Manage icon in the upper right corner.
4. Click Operations. The Operations palette displays.
5. Click SSH. You can add or update a public key and remove VM SSH public
keys from this palette.

646

IBM Cloud Orchestrator 2.4.0.2: User's Guide

6. To upload a SSH public key, copy and paste your SSH key in the Public Key
field and click Submit in the Add or update VM SSH public key section. If
you already have a public key in the Public Key field, the key is replaced.
Important: Do not copy the key from the console output of the Linux
command more. This can introduce line breaks into the key that might render it
invalid.
7. To remove VM SSH public keys, click Submit in the Remove VM SSH public
keys section.
Results
You have added a new VM SSH public key or removed VM SSH public keys.
LTPA keys:
Lightweight Third-Party Authentication (LTPA), is an authentication technology
used in the web application that is deployed into the cloud infrastructure.
About this task
There are various tasks you can do with LTPA keys, including regenerating keys,
importing keys and exporting keys.
To configure the LTPA keys, follow these steps:
Procedure
1. Click PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays.
2. Select the WebSphere Application Server virtual application instance. The
virtual application instance details display.
3. Click the Manage icon.
4. Select Operations. The Operations palette opens.
5. Select the WebSphere Application Server application. The deployment
operations palette displays the operations on the right. Now you can manage
the LTPA keys.
6. Regenerate LTPA keys. To regenerate LTPA keys, expand Regenerate LTPA
keys in the Deployment operations palette. Click Submit. A confirmation
dialogue window displays. Click Yes to confirm that you want to regenerate
the LTPA keys.
The operation status displays in the Operation Execution Results palette. When
the operation displays as successful, the LTPA keys are regenerated.
7. Import LTPA keys. To import an LTPA key, expand Import LTPA keys in the
Deployment operations palette. Click Browse to locate the LTPA key that you
want to import. Click Submit. A confirmation dialogue window displays. Click
Yes to confirm that you want to import the LTPA key. The operation status
displays in the Operation Execution Results palette. When the operation
displays as successful the LTPA key is imported.
8. Export LTPA keys. To export LTPA keys, expand Export LTPA keys in the
Deployment operations palette. Click Submit. The operation status displays in
the Operation Execution Results palette. When the operation displays as
successful the LTPA key is exported. The exported key can be downloaded
through the link that is listed in the operation status section.
Chapter 7. Managing and deploying virtual patterns

647

Working with virtual application instances

Each deployment of a virtual application represents a running virtual application
instance on the cloud environment. You can view and monitor deployed virtual
application instances from the Virtual Application Console.

Before you begin

Deploy a virtual application from IBM Cloud Orchestrator to the cloud
environment.

About this task

To manage a virtual application instance:

Procedure
1. Click PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays. The virtual application instances are
listed by name. You can sort the list by application name or sort by status.
Attention: You can also view the virtual application instances on a page
where all instances, such as virtual appliance instances, virtual system
instances, shared services instances and database instances are listed. Click
PATTERNS > Instances > Virtual Application Instances. Every instance
running on the IP address are listed.
2. From the left panel of the Virtual Application Instances palette, select the
virtual_application_instance that you want to review.
3. The Maintain view displays to the right. The details include a list of virtual
machines provisioned on the cloud infrastructure for that deployment, the IP
address, virtual machine status, and role status. Role is a unit of function that is
performed by the virtual application middleware on a virtual machine.
The status values are listed in the following table:
Table 81. Possible status values for a deployed virtual application

648

Status

Deployment description

Virtual machine description

LAUNCHING

The virtual application is

being deployed.

The virtual machine is being

provisioned on the
infrastructure cloud.

INSTALLING

Not applicable

The components of the

virtual application are being
provisioned on the virtual
machine.

RUNNING

Resources are being

provisioned on the
infrastructure cloud.

The components of the

virtual application are
running on the virtual
machine and can be
accessed.

TERMINATED

The deployment process is

stopped.

The virtual machine is

stopped.

FAILED

The deployment process

could not be started due to
either the application
configuration or a failure
occurring in the
infrastructure cloud.

The virtual machine did not

start successfully.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

4. View the virtual machine role health status information. For example, a red
check mark is located on the green status arrow when the CPU is critical on the
virtual machine.
5. Click Endpoint to view the endpoint information for a given role. For a
deployment with DB2 you can have more than one endpoint, for example, an
endpoint for application developer one for database administrator.
6. Click Logs to view the log information. For more information, see Viewing
virtual application instance logs on page 650.
7. Click Manage in the top right for more advanced monitoring details and
operations. The Virtual Machine Monitoring page displays. If you want to
return to the Maintain view, click Maintain in the top right. For more
information about monitoring, see Monitoring virtual application instances
on page 650.

Results
Your virtual application instance is successfully deployed and started. To stop the
virtual application instance, select the application from the list, and click Stop.
However, a stopped deployment cannot be restarted.
To redeploy a virtual application, select the virtual application from the Virtual
Application Patterns palette, and click the Deploy icon in the Pattern Builder.
To remove a stopped application, select it from the Virtual Application Patterns
palette, and click Delete.

What to do next
After you deploy your virtual application, you can use the IP address of the virtual
machines to access the application artifacts. For example:
To gain access to your virtual machine after deployment type:
ssh -i id_rsa.txt virtuser@<your_workload_ip>

For SCP:
scp -i id_rsa.txt myfiles.txt virtuser@<your_workload_ip>

You can now log in to your virtual machine without a password.

To gain root access:
sudo su -

To run a command with root access:

sudo /sbin/ifconfig

You can view and monitor statistics for your deployed virtual machines and
download and view the log files from the user interface. For more information, see
Monitoring virtual application instances on page 650.

Chapter 7. Managing and deploying virtual patterns

649

Monitoring virtual application instances

Use reports and charting to monitor the status and performance of your deployed
virtual application instances and machines.

Before you begin

Your applications must be deployed and all of your virtual machines started before
you can monitor results.
The user who deployed the application. along with those with access or the
administrator, can see the monitoring information for the deployment.

About this task

Use the user interface to monitor the following statistics for your deployed virtual
machines.
v Memory
v Network
v Process
v Storage
Use the user interface to monitor middleware:
v Roles

Procedure
1. Click PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays.
2. Select a virtual_application_instance . The virtual application instance details
display to the right.
3. Click the More information and advanced operations icon located in the upper
right corner.
4. Click Virtual Machine Monitoring. The Virtual Machine Monitoring palette
displays. Select a virtual machine that you want to monitor. The Memory,
Process, Network and Storage monitoring charts display.

Results
You have viewed and monitored virtual application instances and machines.
Viewing virtual application instance logs:
You can view logs of the virtual application instances.
Before you begin
Your virtual application patterns must be deployed and all of your virtual
machines started before you can monitor results.
Procedure
1. Click PATTERNS > Instances > Virtual Application Instances. The Virtual
Application Instances palette displays with the virtual application instances
listed.
2. Select a virtual_application_instance. The details display to the right.

650

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. Click Log, located under the VM Status column to view the virtual machine
status logs. The Log Viewer palette displays with organized log sections, such
as operating system log, pattern type plug-in log and agent log.
The following types of logs can be viewed in the Log Viewer:
v Lightweight Directory Access Protocol (LDAP) logs:
/home/idsldap/sqllib/log
db2dump
db2dump/events
db2dump/stmmlog files
/home/idsldap/idsslapd-idsldap/etc and logs
/var/idsldap/V6.3 log files
v WebSphere Application Server (WAS) logs:
logs/server1 files
logs/ffdc files
Attention: If you have specified additional log files or directories to
monitor in the Logging Policy, these logs also display in this list.
The log viewer is used to view the trailing 10 lines of the log you selected.
New log entries are appended into the log viewer as they occur. The log viewer
has several actions that control the behavior of the log viewer.
You can specify a string to filter what files are displayed in the log viewer.
Strings can be prefixed by a tag that specifies one or more elements of the logs
to be examined. The following tags are supported: role, dir, vm, and file.
role:DB2
Specifies files that belong to a role with a name that contains "DB2".
dir:var Specifies files with an absolute path that includes a directory name that
contains "var". The dir: tag applies to the entire path, with the
exception of the file name.
vm:application
Specifies files on a virtual machine with a name that contains
"application".
file:trace
Specifies files that have names that contain the word "trace".
If a tag is not included in a search string, the filter is assumed to have the file:
tag.
Multiple tags can be used in conjunction.
role:DB2,trace
Specifies files with a name that contains "trace", and that belongs to a
role with a name that contains "DB2".
Ensure that the tags: "role", "dir", "vm", and "file" are lowercase, or they are not
recognized as tags. The strings following the tags, are case insensitive. For
example, the string "role:WAS" will match a role name "WAS" as well as a role
named "was", but the string "ROLE:was" does not match anything, because
ROLE is not recognized as a valid tag. After entering a string in the filter box,
click Go to apply the filter to the tree.
4. Click Download All to download all files in the log viewer. It is only displayed
when no filter string has been entered, or when the filter input box has been
cleared. Clicking Download All returns an archived, compressed file containing
all of the logs on the virtual machine. If there are multiple virtual machines
Chapter 7. Managing and deploying virtual patterns

651

displayed in the log viewer, a separate archive file will be returned for each
virtual machine. When you enter a string into the filter box to select a subset of
logs, Download All is replaced by Download Filtered. Clicking Download
Filtered downloads all of the files that are displayed in the filtered tree as a
single archive file.
5. You can also view the log files in the Virtual Application Console. After you
select the virtual application instance and the details display to the right, you
can click the More information and advanced operations icon located in the
upper right corner. Select the virtual machine for which you want to view logs.
Click Logging on the dashboard.
6. Expand each section to view the logs.
7. Optional: Download the log file. After you expand the log type and select a
log, you can click the green arrow to download the log.
Results
You have viewed the logs associated the virtual application instances and the
virtual machines that they run on.

Working with shared services

Shared services provide a predefined virtual application pattern that is deployed
and shared by multiple application deployments, such as virtual applications and
virtual systems in the cloud.
To view shared services, you must be assigned the admin role.
A shared service provides certain runtime services to multiple applications or
services to the end user on behalf of multiple applications. Only one instance of a
type of shared service can be deployed in a cloud group. This shared service can
be used by all application deployments in the cloud group.
Shared services provide the following features:
v A plug-in design service providing full lifecycle management capabilities in the
same way as a virtual application.
v Specific runtime services to multiple applications, or services to end-users on
behalf of multiple applications
v A simplified consumer (users/application deployments) and provider
(implementation/Shared Service deployment) model.
v Viewed as a multi-tenant service.
Several shared services are offered by default and can be deployed as needed.

Deploying shared services

Use the IBM Cloud Orchestrator user interface to deploy and manage shared
services.

Before you begin

To view shared services, you must be assigned the admin role.

652

IBM Cloud Orchestrator 2.4.0.2: User's Guide

About this task

Only one instance of a type of shared service can be deployed in a cloud group.
This shared service can be used by all application deployments in the cloud group.
To deploy a shared service, complete the following steps:

Procedure
1. Click PATTERNS > Deployer Configuration > Shared Services.
2. In the left pane of the Shared Services window, select the shared service that
you want to deploy.
3. Click the Deploy icon. The Configure and deploy application window is
displayed.
4. Provide information into the fields to configure the shared service. The
information that you must provide differs depending on the shared service that
you are working with.
5. Click OK. The Deploy Pattern window is displayed.
6. Complete the following fields to deploy the application as a shared service:
Name Specifies that name of the application that is being shared as a service.
Do not use more than two consecutive underscore characters in a
shared service name.
Target cloud group
Provides information related to cloud groups.
SSH Key
If you want to upload a public key so that you can connect to the
deployed virtual machines using SSH, click Advanced options and
complete the SSH section. If you do not have an existing SSH key pair,
you can generate one that can be reused with other deployments by
clicking Generate. The SSH Key field populates with the generated
public key. Select Download or Download (PKCS1 format) to save the
private key to your local system.
Schedule deployment
Specifies the start and end dates for the deployment.
7. To stop the shared service, click the Stop the selected shared service icon. The
shared service status is displayed as STOPPED in the details.

Monitoring shared services

Use the IBM Cloud Orchestrator user interface to monitor the shared service
instances that you deployed in your environment.
Complete the following steps:
1. Click PATTERNS > Instances > Shared Service Instances.
2. Select the shared service that you want to monitor.
Important: Ability to view instances of shared services in the user interface
requires that users have the admin role. Additionally, access to each shared service
instance must be granted to each individual user.

Chapter 7. Managing and deploying virtual patterns

653

Monitoring - Application
The Monitoring - Application shared service can be deployed to one or more
cloud groups to provide a reference to an external Tivoli Monitoring installation
Version 6.2.2 Fix Pack 5 or later. Once created, the UNIX or Linux OS monitoring
agents and the Workload monitoring agent that are provided in the virtual
application workloads are automatically connected to a defined instance of a Tivoli
server by using the supplied primary and fail-over Tivoli Enterprise Monitoring
Server, protocol, and port. The URL for the Tivoli Enterprise Portal Webstart
console is provided, so cloud administrators are presented with a monitoring link
in the console to launch to the Tivoli Enterprise Console.
You must install the latest Application Support and Language Pack files for the
Workload monitoring agent on the Tivoli Enterprise Monitoring Server and Tivoli
Enterprise Portal Server before creating the shared service and deploying patterns
so that Tivoli Monitoring displays the new agents.

Deploying a monitoring shared service

Use the user interface to deploy a monitoring shared service to the system. The
monitoring service is shipped with the product in the foundation pattern type.
This process includes adding the shared service and deploying the shared service
into the cloud system to create a shared services instance.

Procedure
1. Click PATTERNS > Deployer Configuration > Shared Services.
2. In the left pane of the Shared Services window, select the MonitoringApplication service.
3. Click the Deploy icon. The Configure and deploy application window is
displayed.
4. Complete the following information:
a. Enter the primary server in the Primary Server field.
b. Enter the secondary server in the Secondary Server field.
c. Select the protocol radio button in the Protocol field. Choose IP.PIPE,
IP.SPIPE, or IP.UDP.
d. Enter the port number in the Port field.
e. Enter the console URL in the Console URL field.
5. Click OK. The Deploy Virtual Application window is displayed.
6. Select the target cloud group.
7. Click Advanced options to set up SSH access. The SSH key provides access to
the virtual machines in the cloud group for troubleshooting and maintenance
purposes.
a. Use one of the following options to set the public key:
v To generate a key automatically, click Generate.
v To use an existing SSH public key, open the public key file in a text editor
and copy and paste it into the SSH Key field.
Note: Do not use cat, less, or more to copy and paste from a command
shell. The copy and paste operation adds spaces to the key which prevent
you from accessing the virtual machine.
b. If you generated a key automatically, click Download to save the private
key file to a secure location. The default name is id_rsa.txt.

654

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The system does not keep a copy of the private key. If you do not
download the private key, you cannot access the virtual machine, unless
you generate a new key pair. You can also copy and paste the public key,
save the key, and reuse the same key pair for another deployment. When
you have the private key, make sure that it has the correct permissions
(chmod 0400 id_rsa.txt). By default, the SSH client does not use a private
key file that provides open permission for all users.
8. Click OK.

Results
You deployed a monitoring shared service as an application.

Enabling TOSCA support for IBM Cloud Orchestrator

IBM Cloud Orchestrator supports importing, deploying, and exporting service
templates according to the OASIS Topology and Orchestration Specification for
Cloud Applications (TOSCA). This enables the consumption of third-party content
provided in a standardized format.

About this task

You can enable TOSCA support by installing and enabling the pattern type
TOSCA Foundation Pattern Type. To enable TOSCA support in your
environment, you must first enable this pattern type.

Procedure
1. Get the /utils/TOSCA/tosca.foundation-1.1.0.0.tgz file from the installation
package.
Log in to the Self-service user interface as a Cloud Administrator.
Click PATTERNS > Deployer Configuration > Pattern Types.
Click New.
Choose the tosca.foundation-1.1.0.0.tgz file from your local drive and click
OK. A new entry is displayed in the palette.
6. Find the TOSCA Foundation Pattern Type entry in the list on the left. This
entry is disabled by default.
7. Click the entry and select Enable from the Status field.
2.
3.
4.
5.

Results
After the pattern type is enabled, you can import TOSCA Cloud Service Archives
(CSARs) that contain service templates that comply with the TOSCA specification.
You can import the templates as Virtual Application Patterns by navigating to
PATTERNS > Pattern Design > Virtual Application Patterns, or as Virtual
Application Templates by navigating to PATTERNS > Pattern Design > Virtual
Application Templates.
Remember: In IBM Cloud Orchestrator, the TOSCA service templates are imported
and deployed as virtual application patters or virtual application templates. Before
you deploy an application pattern imported from a TOSCA CSAR, you must
perform the basic configuration for virtual application patterns, such as
configuration of cloud groups or import of base images.

Chapter 7. Managing and deploying virtual patterns

655

Configuring the RPM repository for the deployment of TOSCA

patterns
Before you can deploy any application patterns imported from TOSCA CSARs, you
must first configure an RPM repository. With the configured RPM repository, you
can install additional RPM packages into the base operating system image that is
used to deploy virtual application patterns.

About this task

You must configure an RPM repository because virtual machines deployed into
private clouds typically do not have access to the internet so default RPM
repositories available on the internet cannot be used.
The TOSCA foundation pattern type includes a plug-in that enables the use of a
dedicated RPM repository. This repository must be hosted on a network that is
accessible by deployed virtual machines. The plug-in also provides configuration
options that you can use to specify all the parameters of an RPM repository.

Procedure
1. Log on to IBM Cloud Orchestrator user interface as administrator.
2. Click PATTERNS > Deployer Configuration > System Plug-ins.
3. From the list on the left, select TOSCA Foundation Pattern Type 1.1.0.0 to
define the pattern type.
4. From the list on the left, select the tosca.rpmrepository 1.1.0.0 plug-in.
5. From the menu on the right, click Configure. The plug-in configuration
window opens.
6. Choose the type of repository to configure. You can choose the types of
repositories to configure or you can select No Repository to disable the
configuration of a previously created repository. You can configure the
following types of repositories:
v ISO Image on NFS
v FTP
v HTTP

Configuring an RPM repository of type ISO Image on NFS

This type of repository refers to an ISO image, typically the image of the operating
system installation DVD, that is located on an NFS server which is accessible by
deployed virtual machines.

Before you begin

Perform the steps described in Configuring the RPM repository for the
deployment of TOSCA patterns.

Procedure
1. From the Repository Type list, select the option ISO Image on NFS.
2. Provide the following parameters:
Repository Name
This parameter specifies the name of the repository that is configured in the
operating system of deployed virtual machines, for example RHEL_6.2_Repo.

656

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Mount point for ISO Image

This parameter specifies a mount point that is created for mounting the ISO
image inside the operating system of deployed virtual machines.
Host name or IP address
This parameter specifies the fully-qualified host name or IP address of the
NFS server that hosts the ISO image. This server must be accessible by
deployed virtual machines.
Repository Path
This parameter specifies the full path of the ISO image file on the NFS
server, including the image file name.

Configuring an RPM repository of type FTP

This type of repository refers to an RPM repository that is available by way of an
FTP server which is accessible by deployed virtual machines.

Before you begin

Perform the steps described in Configuring the RPM repository for the
deployment of TOSCA patterns on page 656.

Procedure
1. From the Repository Type list, select the option FTP.
2. Provide the following parameters:
Repository Name
This parameter specifies the name of the repository that is configured in the
operating system of deployed virtual machines, for example RHEL_6.2_Repo.
Mount point for ISO Image
This parameter does not have any meaning for the FTP repository type.
Host name or IP address
This parameter specifies the fully-qualified host name or IP address of the
FTP server that hosts the repository. This server must be accessible by
deployed virtual machines.
Repository Path
This parameter specifies the full path of the repository on the FTP server.

Configuring an RPM repository of type HTTP

This type of repository refers to an RPM repository that is available by way of an
HTTP server which is accessible by deployed virtual machines.

Before you begin

Perform the steps described in Configuring the RPM repository for the
deployment of TOSCA patterns on page 656.

Procedure
1. From the Repository Type list, select the option HTTP.
2. Provide the following parameters:
Repository Name
This parameter specifies the name of the repository that is configured in the
operating system of deployed virtual machines, for example RHEL_6.2_Repo.

Chapter 7. Managing and deploying virtual patterns

657

Mount point for ISO Image

This parameter does not have any meaning for the HTTP repository type.
Host name or IP address
This parameter specifies the fully-qualified host name or IP address of the
HTTP server that hosts the repository. This server must be accessible by
deployed virtual machines.
Repository Path
This parameter specifies the full path of the repository on the HTTP server.

Disabling the configuration of an RPM repository

Disable the configuration of an RPM repository to revert to the default
configuration.

Procedure
1. Perform the steps described in Configuring the RPM repository for the
deployment of TOSCA patterns on page 656.
2. From the Repository Type list, select the option No Repository.

Results
By selecting this option, you disable the configuration of an RPM repository and
you keep the default configuration defined in the base operating system image
used for virtual application deployment.

Example
You can use this option if the deployed virtual machines have access to default
repositories on the internet or if the base operating system image is already
configured to use specific RPM repositories.

Configuring Chef support for TOSCA based virtual application

patterns
You can configure the use of Chef automation in context of TOSCA patterns. The
TOSCA Chef support inside IBM Cloud Orchestrator is a plug-in as part of the
TOSCA Foundation Pattern Type.

About this task

For maximum flexibility, you can configure a Chef client for use with the TOSCA
Chef plug-in, in the required version. Chef client is not shipped with IBM Cloud
Orchestrator. To configure the Chef client for use with virtual application patterns,
complete the following steps.

Procedure
1. To use Chef with virtual application patterns, you must upload an RPM
containing a Chef client. Retrieve the Chef client RPM from Opscode.
2. Configure the TOSCA Chef Plug-in repository:
a. Go to Patterns > System Plugins and choose the tosca.chef plug-in.
b. Click Configure in the upper right corner. The configuration options for the
TOSCA Chef plug-in appears.
c. Choose Chef Deployment Mode: Chef Solo, as TOSCA service templates,
imported as virtual application patterns, are using Chef Solo deployments.

658

IBM Cloud Orchestrator 2.4.0.2: User's Guide

d. In the Chef client package, click Browse and choose the Chef RPM that
you downloaded from Opscode to your local drive.
e. Click Update to activate your changes.
The TOSCA service template, imported as virtual application pattern, uses this
RPM package for installing Chef Solo on the deployed VM and executing the
Chef artifacts.

Chapter 7. Managing and deploying virtual patterns

659

660

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 8. Managing a hybrid cloud

A hybrid cloud is a cloud computing environment in which an organization
provides and manages some resources in house and has others provided externally.
For example, an organization might use a public cloud service, such as Amazon,
for archived data but continue to maintain in house storage for operational
customer data.
IBM Cloud Orchestrator provides a component called Public Cloud Gateway to
integrate with public clouds.
Examples of public clouds are:
v Amazon AWS EC2.
v IBM SoftLayer.
v Non IBM OpenStack.
The Public Cloud Gateway is installed on the Central Server 2 machine during the
installation of IBM Cloud Orchestrator.

Public Cloud Gateway overview

The Public Cloud Gateway is a web application that provides an OpenStack API
compatibility layer so that the Amazon Elastic Compute Cloud (Amazon EC2),
IBM SoftLayer, and non-IBM supplied OpenStack, work like the standard
OpenStack, Cinder, and Glance instances.
The Public Cloud Gateway is automatically installed on the Central Server 2
machine as part of the IBM Cloud Orchestrator installation process. For more
information about installing Public Cloud Gateway, see the related installation
topics at Chapter 2, Installing, on page 15. You can deploy and manage virtual
machines and storage across both private and public clouds, for example, Amazon
EC2. Public Cloud Gateway calls the management APIs of the Remote Cloud to
perform the OpenStack API.
Note: The Public Cloud Gateway provides a subset of the available OpenStack
API. See OpenStack API support on page 664.
The invocation of the management APIs of the Remote Clouds might go through
an HTTP/HTTPS proxy.
Note: For configuration of a proxy see Remote Cloud API proxy configuration
on page 695.
Access to the provisioned virtual machine instance is either through a VPN
connection the on-premises IBM Cloud Orchestrator instance to the management
network of the provisioned virtual machine instances or through the internet.
Note: The Remote Cloud capabilities together with the Public Cloud Gateway
configuration define which connectivity to the provisioned virtual machine
instance is used.

Copyright IBM Corp. 2013, 2015

661

Note: The configuration of the VPN between the IBM Cloud Orchestrator
on-premise instance and the remote clouds has to be done out of band depending
on the available or chosen hardware devices available on the on-premise site. Both
the Business Process Manager node and the Workload Deployer node require
access to the remote cloud via VPN.
Configuration of the Public Cloud Gateway is done in the following steps:
v Configure config.json in /opt/ibm/pcg/etc on the node were the Public Cloud
Gateway is installed.
v Configure credentials.json in /opt/ibm/pcg/etc on the node were Public
Cloud Gateway is installed.
v Configure access to the setup regions.
See the related topic for more information about how the Public Cloud Gateway
fits into the IBM Cloud Orchestrator product architecture.
Review the list of capabilities and limitations for the Public Cloud Gateway.

Capabilities and limitations

This topic describes capabilities and limitations for IBM Cloud Orchestrator in
managing hybrid clouds together with the Public Cloud Gateway using OpenStack.
New features and functions
v
v
v
v
v

Project-level quota support.

Multi-tenancy support.
Deploy single virtual server offering.
Dashboard support.
Assigned Resources view support.

v Offerings for key management: register and unregister key.

v Attach additional volume.
v Windows operating system is supported as a guest.
General limitations
v IBM Cloud Orchestrator Administration (Project and Admin section) is not
supported for Public Cloud Gateway managed regions.
v The Identity Panel must be used to configure Availability Zones to Domains and
Projects.
v Deploying a cloud service using stacks (OpenStack Heat deployment) is not
supported for Public Cloud Gateway managed regions.
v Unable to import images from sources outside of public cloud repositories. If
special images are required by patterns, this scenario is not supported.
v Supports only single predefined Dynamic Host Configuration Protocol (DHCP)
network.
v Supports single or dual NIC depending on remote IaaS (Amazon EC and NIOS
single NIC, IBM SoftLayer 1 or 2 NIC(s) depending on configuration).
v SoftLayer only supports to resize the CPU and RAM and not the Primary Disk.
v When you add the Default add disk add-on to SoftLayer images in Virtual
System (Classic) Patterns, ensure that you request disk sizes that match the
available disk options in SoftLayer. Otherwise, the add-on will fail to format and
mount the disk when deploying the pattern.

662

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Windows images in Amazon EC2 and SoftLayer are automatically activated and
license keys are provided by the remote cloud.
v For Amazon EC2, the resize of a virtual machine instance is only possible in the
stopped state.
Public Cloud Gateway capabilities within IBM Cloud Orchestrator using
Workload Deployer
v vSysClassic using scp-init images.
v Deploy a virtual system.
v Stop and start a virtual system instance.
v Remove a virtual system instance.
v Script packages support is available.
v Configure administrator password on a virtual machine with images containing
the Activation Engine.
v Single Dynamic Host Configuration Protocol (DHCP) IP Group.
v User add-on support is available.
v Disk add-on is available for virtual system parts.
Public Cloud Gateway limitations within IBM Cloud Orchestrator using
Workload Deployer
v Public Cloud Gateway vSysNext is not supported.
v Network Interface Controller (NIC) add-on is not supported.
v Setting root password not supported for scp-init images.
v A Windows licence key is required in the Workload Deployer UI but Windows
images will get license key and activation by remote cloud environment for
Amazon EC2 and SoftLayer.
v Due to the build in size limitations of user data that can be passed into Softlayer
during provisioning, the user data passed during the Workload Deployer pattern
deployments will be reduced to the given username and password needed to
setup the machine. This means that additional user data passed in during the
provision by the end user will not be available on the machine and script
packages and other components relying on such user data might not work as
expected.
v On EC2 and Softlayer Windows, the images are created fully licensed and
activated. Therefore any given Owner, Organization and License data filled in
during provisioning of a pattern in Workload Deployer will be ignored.
Public Cloud Gateway capabilities within IBM Cloud Orchestrator
v Deploy a single virtual server offering.
v Stop and start a virtual system instance.
v Attach and detach a volume.
v
v
v
v

Remove a virtual system instance.

Run script packages.
Resize virtual system instance.
Single predefined Dynamic Host Configuration Protocol (DHCP) network only.

Public Cloud Gateway limitations within IBM Cloud Orchestrator

v Unable to retrieve hypervisor resource information when used in a non-IBM
supplied OpenStack configuration.

Chapter 8. Managing a hybrid cloud

663

v OpenStack command line clients are not supported for Public Cloud Gateway
regions.
v OpenStack API support. The Public Cloud Gateway supports a limited set of
OpenStack APIs.
Volume provider limitations
v For NIOS regions, neither name nor description are supported.
v For Amazon EC2, name and description is supported.
v For SoftLayer, name is supported and description is not supported. If no name is
supplied, a name is created in the form:
HybridStorage-<volume_size>GB-<date>

.
v For SoftLayer, there is no mount point information returned and hence
hardcoded /mnt is returned as mount point.
v For Amazon EC2 and SoftLayer, the IBM Cloud Orchestrator Cinder toolkit
attach the volumes but it does not format and mount the volumes on the
servers.
v For SoftLayer, the size of the volume is defined by the size options available for
SoftLayer Portable Storage. The SoftLayer Portable Storage is attached as a local
storage, which means that only a subset of the size options is available. Storage
is only attached in the granularity available for Portable Storage. For example,
even if you request 1 GB, you get 10 GB.

Amazon VPC support

The Public Cloud Gateway supports the placement of machines in different
subnets and security groups when a non-default VPC is configured for a given
account and region.
This capability is available when the only supported platform for your account is
VPC. It is not enabled when other supported platforms are listed, for example,
EC2. You can check the supported platforms of your account on the EC2
dashboard in the Account Attributes section. You must perform additional
configuration tasks to use Amazon VPC support. See Configuring the Public
Cloud Gateway for Amazon EC2 on page 697 and Configuring subnets and
security groups in a non-default VPC region on page 702.

Amazon API support

The Public Cloud Gateway supports only regions that are accessible using Version
2 Security.
You cannot connect to Amazon regions that support only Version 4 Security, for
example, Europe-Central Frankfurt and China Beijing.

OpenStack API support

The Public Cloud Gateway supports a limited set of OpenStack APIs.
Supported OpenStack APIs include:
v OpenStack Nova
v OpenStack Glance
v OpenStack Cinder
Supported OpenStack Nova API

664

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Create (boot) a virtual machine with:

SSH key
Availability zone
Single DHCP network
v List virtual machine instance:

v
v
v
v
v

Filter by status
Filter by SSH key name
Delete virtual machine
Start / stop virtual machine
Show virtual machine detail
List images
Show image detail

v
v
v
v
v
v

List Availability Zones

List Networks providing a single DHCP network
List Extensions
List Flavors
Show Flavor details
Get version info

v Get Limits
v Show Network providing a single DHCP network
v Query quota for tenant
v
v
v
v

Query quota defaults for tenant

Set quota for tenant
Delete quota of tenant
Attach Volume

v Detach Volume
v Create key pair providing the SSH key import within the request
v List key pairs
v Delete key pair
Supported OpenStack Glance API
v List images
v Show image detail
Supported OpenStack Cinder API
v Create volume
v List volumes
Filter by status
v Filter by status
v Show volume detail
v Delete volume
v List volume types
Single hardcoded entry
Note: All other OpenStack documented API's are not supported by the Public
Cloud Gateway.
Chapter 8. Managing a hybrid cloud

665

Configuring the Public Cloud Gateway

The Public Cloud Gateway is deployed as part of the IBM Cloud Orchestrator
installation on the Central Server 2 machine. However, the Public Cloud Gateway
is not enabled by default and certain updates to the configuration files are required
before you can use the Public Cloud Gateway.

Before you begin

Ensure that the prerequisites are satisfied.

About this task

To configure the Public Cloud Gateway, set up the following configuration files:
v admin.json
v config.json
v credentials.json
v flavors.json
By default, these files are located on Central Server 2 in the /opt/ibm/pcg/etc
directory. When the Public Cloud Gateway is installed, default values for all
parameters are provided except cloud access keys. Administrators must only change
these settings in the configuration files that affect their particular setup.
The configuration of the Public Cloud Gateway is slightly different depending on
the actual remote cloud:
v Configuring the Public Cloud Gateway for Amazon EC2 on page 697
v Configuring the Public Cloud Gateway for SoftLayer on page 703
v Managing non-IBM supplied OpenStack using the Public Cloud Gateway on
page 708
There are a set of Common configuration tasks on page 675 that are common
across all supported remote clouds.
Related reference:
Region names displayed incorrectly in the Virtual Image page on page 1063
A known issue exists where IBM Cloud Orchestrator removes the name after an
_ in the region name when registering images.
Unable to connect to a public cloud due to missing credentials on page 1063
In the Public Cloud Gateway, you might receive the error Unable to connect to
public cloud due to missing credentials.
Loss of functionality in Public Cloud Gateway cloud groups on page 1062
Loss of functionality may occur in Public Cloud Gateway cloud groups in IBM
Cloud Orchestrator, where there has been heavy load on the Public Cloud Gateway
cloud groups.

666

IBM Cloud Orchestrator 2.4.0.2: User's Guide

SSH key management

The Public Cloud Gateway provides the capabilities for SSH key management, that
is, OpenStack key pairs.
For Amazon EC2, , and SoftLayer you can support register and deregister SSH key
offerings in the catalog.
For information about SSH keys, see the description of the register and unregister
key offerings:
v Registering a key pair on page 322.
v Unregistering a key pair on page 322.
Assumptions:
v Key pairs are subject to quota. A create key pair request might fail due to
reaching the quota limits per project.
v Key pairs are subject to multi-tenancy. Key pairs are scoped on a per project
basis.
Limitations:
v IBM SoftLayer does not allow storing the same SSH key (with the same
fingerprint) multiple times under different key pair names. If an SSH key is
registered multiple times with the Register a keypair offering, the deployment
fails when the SSH key is deployed the second time during the deploy single
server offering with a different name but with the same fingerprint.
Remove the second registered SSH key with the same fingerprint using the
Unregister a key pair offering. Use every time you register an SSH key a
newly created one.
v The remote clouds have different assumptions about the scope of an SSH key.
IBM SoftLayer and Amazon EC2 SSH keys have an account scope. The Public
Cloud Gateway postfixes the name of the SSH key with a <tenantuuid> when
the SSH key is deployed on the remote cloud. On the Keypair list/show or
instance list/show the <tenantuuid> is removed.
In non-IBM supplied OpenStack, the SSH key is deployed through the
OpenStack EC2 provider of the remote OpenStack. In OpenStack, SSH keys
have a project level scope.

Multitenancy support
The Public Cloud Gateway provides capabilities for multitenancy.
These capabilities are in addition to the general multitenancy capabilities in the
core product.
The Public Cloud Gateway contains the following capabilities related to
multitenancy:
v Supports non-default domains and projects.
v Limits the view of resources on project scope.
v Creates resources in scope of a project.
v Supports quotas on a per project and per region base.
Mapping to OpenStack concepts:
The Public Cloud Gateway supports the following OpenStack constructs
and resources in a multitenancy model:
Chapter 8. Managing a hybrid cloud

667

v Virtual machine instances.

v Storage volumes.
v SSH keys.
The following resources are public within the remote cloud account level:
v Images.
v Networks.
Scoping assumptions within the Public Cloud Gateway:
v A region must map to a single remote cloud account.
v The project to which the cloud administrator belongs to, must be
mapped for each region to a credential which can see all resources
within a remote cloud account. The default project name within IBM
Cloud Orchestrator is admin, where the cloud administrator belongs to.
Mapping capabilities within the Public Cloud Gateway:
v The config.json defines the regions exposed by the Public Cloud
Gateway. Each region maps to a single remote cloud account and a data
center within the account.
v Accounts in a remote cloud and datacenter map to Region and
Availability Zone in OpenStack.
v The Administration user interface identity section maps Region and
Availability Zone in OpenStack to a domain and then to a project within
the domain.
v The credential.json maps projects to credentials within the remote
cloud account. There are 2 options:
Map credentials to projects globally.
Map credentials to projects within the scope of a region.
Note: If you have multiple regions per remote cloud type (Amazon EC2
or SoftLayer) it is required to do the mapping in scope of a region,
because it is not possible to share a userid in the remote cloud among
accounts.
Multitenancy concepts provided by the Public Cloud Gateway:
Share an Amazon AWS EC2 or SoftLayer account across projects using a single
set of credentials:
When a resource is created in the remote cloud, it is created within a
project scope. This means that you can only see the resource that belongs
to the project you are logged into. This feature is transparent in the Public
Cloud Gateway.
Note: Resources are either tagged by project ID or separated by
namespace. If you log on to the remote cloud management console, you
can see the tags and namespaces for the various resources. In the
credentials.json file there is a new construct to provide a mapping of all
projects within a region to a specific credential. An example statement for
Amazon AWS EC2 is:
{
"tenantName":"*",
"region": "yyy",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
}

668

IBM Cloud Orchestrator 2.4.0.2: User's Guide

An example statement for SoftLayer is:

{
"tenantName":"*",
"region": "yyy",
"user_id":"xxx",
"api_access_key":"xxx"
}

Share a cloud account across projects using dedicated credentials per project:
The Public Cloud Gateway contains a configuration file that maps the
credentials used for a region to a project. This feature allows you to supply
different logon credentials on a per project and per region basis.
Note: The project of the cloud administrator must be mapped using a
credential which can see all the resources of the other projects within the
same account. Failure to this would result in deployment errors using
Workload Deployer scenarios.
Limitations:
v The multitenancy support does not provide a physical segregation of resources
because they still belong to the same account. It provides different views of the
account on a per project basis.
v The network is shared across an account.
v Storage comes from a shared pool.
v Images are public.

Quota support overview

The Public Cloud Gateway provides capabilities for quota management.
The following are the types of quota definitions in Public Cloud Gateway:
v A single global default quota used if no project level definitions are set.
v Per region and project quota set managed by the administration view in the
project detail section.
The following quotas are supported in Public Cloud Gateway. This is only a subset
of the OpenStack defined set:
instances
Total number of instances that can be provisioned.
cores

Total number of cores that can be consumed.

ram

Total RAM size in MB that can be consumed. Must be larger than the
gigabytes quota value.

gigabytes
Largest size of a single volume in gigabytes.
volumes
Number of volumes that can be created.
key_pairs
Number of key pairs that can be created.
The following actions can be done on quotas:
v Set global quota defaults. Maintained within the Public Cloud Gateway
configuration.
Chapter 8. Managing a hybrid cloud

669

v Query and Set per project quota defaults. Maintained within the administration
view in the project details.
v Delete a project quota. Supported only through OpenStack API calls. Not
supported through the IBM Cloud Orchestrator UI.
Assumptions:
v The Administrator of the Public Cloud Gateway region must ensure that the
sum of the per project quota does not exceed the region capability.
v Quotas are enforced on a per project and region base.

Network planning
Public Cloud Gateway scenarios require a set of network configuration to
successfully provision resources within the remote cloud. This section provides an
overview about which network configuration is assumed and required.
v Access to the remote cloud REST API entry points.
v Communication from the IBM Cloud Orchestrator management stack to and
from the provisioned virtual machine instances.

Access to the remote cloud REST API entry points

During the management lifecycle, the Public Cloud Gateway requires access to the
remote cloud REST API entry points for:
v Amazon AWS EC2 REST API.
v SoftLayer REST API.
v EC2 provider running in the non-IBM supplied OpenStack environment.
Public Cloud Gateway provides two scenarios for accessing the remote cloud API
REST entry points:
v Direct connection from Central Server 1 where the Public Cloud Gateway
connects to the remote entry point.
v Indirect connection via a customer provided proxy server. See Remote Cloud
API proxy configuration under the common configuration tasks (refer to
Remote Cloud API proxy configuration on page 695).

Connectivity from IBM Cloud Orchestrator management stack to

and from provisioned virtual machines
In addition to the remote cloud REST API entry points, communication several
management actions require access to the provisioned virtual machine instances.
Examples are:
v Running of scripts.
v Actions from the Instance View.
In the Public Cloud Gateway scenarios, the remote clouds will be in remote clouds.
It is assumed that the connectivity from and to the IBM Cloud Orchestrator
management from the remote virtual machine instance is provided by the
customer. This is an example list of what could be used to establish the
communication requirements:
v Open VPN.
v Amazon EC2 VPN gateway.
v Vyatta / Fortigate Security Appliance (FSA) in SoftLayer.

670

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The following network protocols are used:

v Ping from the Workload Deployer node to the provisioned virtual machine on
the IP address returned as public.
v SSH from Central Server 1 and the Workload Deployer node to the provisioned
virtual machine on the IP address returned as public.
v Protocols used by any of the agents running on the provisioned virtual machine
to their infrastructure servers. For example, Tivoli Monitoring.
v For Windows provisioning additional ports have to be opened:
RDP port (3389) must be enabled in the security group(s) on Amazon EC2,
when you create the image, and it must be enabled in the Default security
group for deployment.
RXA communication ports from Central Server 1 and the Workload Deployer
node to the provisioned virtual machine. Ports 135,139. For details see:
http://www-01.ibm.com/support/knowledgecenter/SS2GNX_5.1.1/
com.ibm.support.tpm.doc/agent/trrxa_enablewin.html and
http://www-01.ibm.com/support/knowledgecenter/SSCKBL_8.5.5/
com.ibm.websphere.installation.nd.doc/ae/cins_cim_rxa_requirements.html.
Note: The network requirements must be in place and working prior to the first
provisioning in the remote cloud using the Public Cloud Gateway.

Amazon AWS EC2 related network planning

This section covers Amazon AWS EC2 specific network planning topics like:
v Supported capabilities.
v Assumptions and limitations.
v VPN.
Introduction:
Amazon AWS EC2 provides three different network models depending on when
the account was created. An account supports either EC2Classic and non-Default
VPC or Default and non-Default VPC.
To exploit all of the capabilities the Public Cloud Gateway supports, it is required
to have an actual account that supports Default and non-Default VPC. All accounts
created after December 2013 should be fine. You can check the account capabilities
using the Amazon AWS EC2 console under Account Attributes on the main EC2
Dashboard. If you see Supported Platforms VPC and Default VPC then your
account supports all Public Cloud Gateway capabilities.
Supported capabilities:
Amazon AWS EC2 distinguishes between three types of networking models:
v EC2Classic.
v Default-VPC.
v non-Default VPC.
Each of the three networking models have specific capabilities and limitations.
Refer to the Amazon Documentation in the EC2 and VPC user guide to
understand the main capabilities and limitations. Public Cloud Gateway supports
all the three network models. The following table provides a quick overview about
the supported capabilities:
Chapter 8. Managing a hybrid cloud

671

Table 82. Supported capabilities of the networking models

Capability

EC2Classic

Default-VPC

Non-Default VPC

Private IP address

Yes

Yes

Yes

Public IP Address

Yes

Configurable per
region

Configurable per
region/project

Hide Public IP
Address

Yes, it is required for

VPN setup

No, done by setting

privateOnly to true

No, done by setting

privateOnly to true

Set Private Subnet

No, EC2Classic
defines subnet

No, Default VPC

defines subnet

Yes, Granularity on
project or region

Set Security Group

No, only Default

security for
EC2Classic is used

No, Default security

of default VPC is
used

Yes, Single Security

group on region per
project granularity

Elastic IP Address

No

No

No

Config

On Amazon account
level

On Amazon account
level

"vpc" property in
config.json on
region definition and
VPC definition in the
Amazon
Management portal

Assumptions and limitations:

v Each virtual machine provisioned by Public Cloud Gateway will get a private IP
address. The available networking model of the Amazon EC2 Account defines
from which subnet the private IP address will be derived.
v Public IP addresses will be derived from a global subnet within Amazon AWS
EC2. These IP addresses are only assigned to a virtual machine as long as the
virtual machine is running. A Stop/Start sequence will assign a new public IP
address to the virtual machine. Public IP addresses are realized via NAT and are
not reachable through a VPN. Public IP addresses can only be reached through
an internet connectivity.
v Elastic IP addresses are not supported.
v Only a single security group can be assigned to a virtual machine controlled by
a Public Cloud Gateway.
v For non-Default VPC only a single subnet or security group must be tagged
with a projectUUID or "*" per availability zone. If either multiple or non of the
subnets are tagged, provisioning fails. If no security group is tagged, the default
security group of the VPC is used.
VPN setup:
Virtual machines can be accessed through a VPN (virtual private network) on their
private IP address. Setting up a VPN is out of scope of this documentation. There
are various options to setup a VPN within Amazon AWS EC2. For example VPN
support in VPC, using a OpenVPN or IPSEC gateway. It is required to setup the VPN
to the private IP address as the public IP addresses are only reachable through an
Internet connectivity.

672

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Upgrading
There are some considerations for the Public Cloud Gateway when you upgrade.
The Public Cloud Gateway includes some new capability for multi-tenancy for
Amazon EC2. See the following topics:
v Multitenancy support on page 667
v Configuring the Public Cloud Gateway for Amazon EC2 on page 697 to set up
the credentials.json
The caching system of the Public Cloud Gateway has changed. See Configuring
caching on page 691.

Upgrading and cache configuration

The Public Cloud Gateway introduces a new caching system with this release.
For details about how to configure the cache, see Configuring caching on page
691.
The existing cacheCounter section in the config.json is deprecated and no longer
active. The following new sections control the caching behavior of the Public
Cloud Gateway:
v cacheTimeout
v QuotaTimeouts
The cacheTimeout section is the direct replacement for the cacheCounter section in
the previous release. While the cacheCounter semantic refreshed the cache after a
given number of queries, the cacheTimeout replaces this semantic by a timeout
value in seconds. In addition, in the current release, the caches are more precise
and are invalidated if the related resource type for a project is modified, that is,
created, deleted, or changed.
You can use the provided values to start, and then adjust them based on the
workload run via the Public Cloud Gateway.

Upgrading Amazon EC2 multi-tenancy

The Public Cloud Gateway has some new capability for multi-tenancy for Amazon
EC2.
The following resource types in Amazon EC2 are tagged with additional properties
to provide a segregated view on a per project base:
v Virtual machine instances
v Volumes
The following tags are added:
TenantUUId
Describes the project to which the virtual machine belongs. The tag must
contain a valid project UUID found in the identity view in the
Administration user interface.

Chapter 8. Managing a hybrid cloud

673

RequestUserUUId
Describes the user to which the virtual machine belongs. The tag must
contain a valid user UUID found in the identity view in the
Administration user interface.
Note: You must set at least the TenantUUID tag so that the virtual machine appears
in OpenStack. The same is valid for existing volumes.
The upgrade is done by adding the above tags to the exiting resources in Amazon
EC2 in the Amazon Management UI. As a result, the instances and volumes appear
in the related projects.
For keypair, the upgrade is done differently because keypairs do not support tags.
The _<project uuid> is a suffix to the name of the keypair. The upgrade of keypairs
is done by renaming the related keypair in the Amazon Management UI.
Note: Existing keypairs cannot be added to IBM Cloud Orchestrator V2.4 so that
they can be used in the Deploying a virtual machine on page 314 offering. They
have to be reimported using the Registering a key pair on page 322 offering.

Performing post-upgrade configuration tasks

You must perform some configuration tasks after upgrading.
Because SoftLayer was not supported in SmartCloud Orchestrator V2.3, after
upgrading the Public Cloud Gateway to V2.4, you must perform some
configuration tasks if you are using SoftLayer.
Complete the following steps:
1. Edit /opt/ibm/pcg/etc/flavors.json adding the following Softlayer section:
"softlayer_default": {
"SL.micro": {"name":"Micro", "cpu":1, "ram":1024, "disk":80},
"SL.small": {"name":"Small", "cpu":1, "ram":2048, "disk":150},
"SL.medium": {"name":"Medium", "cpu":1, "ram":4096, "disk":400},
"SL.large": {"name":"Large", "cpu":2, "ram":8192, "disk":840},
"SL.xlarge": {"name":"Extra Large", "cpu":2, "ram":8192, "disk":840}
}

The final flavors.json looks like this:

{
"default": {
"m1small": {"name":"Small", "cpu":1, "ram":1024, "disk":150},
"m1medium": {"name":"Medium", "cpu":2, "ram":4096, "disk":400},
"m1large": {"name":"Large", "cpu":4, "ram":8192, "disk":840},
"m1xlarge": {"name":"Extra Large", "cpu":8, "ram":16384, "disk":1680},
"c1xlarge": {"name":"High-CPU Extra Large", "cpu":20, "ram":8192, "disk":1680},
"m2xlarge": {"name":"High-Memory Extra Large", "cpu":6, "ram":16384, "disk":410}
},
"nioRegion1": {
"m1small": {"name":"Small", "cpu":1, "ram":1024, "disk":150},
"m1medium": {"name":"Medium", "cpu":2, "ram":4096, "disk":400},
"m1large": {"name":"Large", "cpu":4, "ram":8192, "disk":840},
"m1xlarge": {"name":"Extra Large", "cpu":8, "ram":16384, "disk":1680}
},
"softlayer_default": {
"SL.micro": {"name":"Micro", "cpu":1, "ram":1024, "disk":80},
"SL.small": {"name":"Small", "cpu":1, "ram":2048, "disk":150},
"SL.medium": {"name":"Medium", "cpu":1, "ram":4096, "disk":400},
"SL.large": {"name":"Large", "cpu":2, "ram":8192, "disk":840},
"SL.xlarge": {"name":"Extra Large", "cpu":2, "ram":8192, "disk":840}
}
}

674

IBM Cloud Orchestrator 2.4.0.2: User's Guide

2. Edit /opt/ibm/pcg/config.json adding the SoftLayer section. See Configuring

the Public Cloud Gateway for SoftLayer on page 703.
3. Edit /opt/ibm/pcg/credentials.json adding the SoftLayer section. See
Configuring the Public Cloud Gateway for SoftLayer on page 703.

Upgrading SoftLayer datacenter names from 2.4 to 2.4.0.x

The data center naming for SoftLayer has changed from IBM Cloud Orchestrator
2.4 to 2.4.0.x.

About this task

If you already used SoftLayer regions within the public cloud gateway
config.json it is required to change the data center names as part of the upgrade
to 2.4.0.x.
Update the dataCenter property within a SoftLayer region definition according to
the description in Configuring the Public Cloud Gateway for SoftLayer on page
703, which provides the new datacenter names.
Note: Update the dataCenter property in config.json before using the SoftLayer
regions after the upgrade.

Common configuration tasks

There are some configuration tasks that you must perform.

Prerequisites
Before configuring the Public Cloud Gateway you must ensure that the following
requirements are satisfied.
General requirements
Depending on the public cloud used by the customer the following
requirements are needed on the cloud that will be integrated.
An Amazon Web Service (AWS) account with Amazon EC2 credentials for
each tenant/project using the Public Cloud Gateway functionality is
required. See the AWS Management Console for more information:
https://console.aws.amazon.com/console/home.
Set up an account in SoftLayer and create one or more users IDs. Each ID
has its own unique password and API access key. The API access key is
required to configure SoftLayer integration in the Public Cloud Gateway.
Network requirements
v Port requirements The Public Cloud Gateway requires access to a
number of ports in the installation environment and in the default
Amazon EC2 security group. If these ports are blocked by a firewall or
used by another process, some Public Cloud Gateway functions will not
work.
Table 83. Ports used by Public Cloud Gateway
Port

TCP or UDP

Direction

Description

22

TCP

Outbound

SSH communication
with the Virtual
Machine instances.

Chapter 8. Managing a hybrid cloud

675

Table 83. Ports used by Public Cloud Gateway (continued)

Port

TCP or UDP

Direction

ICMP

Description
ICMP communication
with the Virtual
Machine instances.

443

TCP

Outbound

HTTPS
communication with:
v Amazon EC2
management
endpoints.

Note: Make sure that the Amazon EC2 security groups are configured
according to the table. For more information about Amazon EC2 security
groups, see http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/
using-network-security.html
v DNS requirements Ensure that the DNS is configured correctly in
both Central Server 2 and Central Server 3. Both Central Server 2 and
Central Server 3 instances must be able to resolve the Amazon EC2
management endpoints as defined in the /opt/ibm/pcg/etc/config.json
file.
Access to public cloud resources
To provision virtual machines or use any services in the public cloud, users
are required to have credentials to access public cloud resources. These
credentials are then used in configuration of the Public Cloud Gateway.
Images in public cloud
To deploy patterns in the public cloud, users are required to provide
pattern-specific private images or image templates in the public cloud
image repositories. See Creating a supported image.

Creating a supported image

You can create a supported image to be deployed with Public Cloud Gateway.

Creating cloud-init images for Nova deployment for Linux

You can create cloud-init images for Nova deployment for Linux.
The image creation is dependent on the target IaaS cloud.
Amazon AWS EC2
v Many of the current Amazon AWS EC2 images are cloud-init enabled.
v If you are using an image that is not cloud-init enabled, follow the
steps to add cloud-init support here: Adding cloud-init to Linux
images on page 336
v All Amazon AWS EC2 image for Linux provide cloud-init support
natively.
v You must make a private copy out of the existing Amazon EC2 images.
Only private images can be used together with Public Cloud Gateway.
Follow the description in the Amazon EC2 documentation here:
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creatingan-ami-ebs.html
v To enable password base authentication, see Password authentication
on Amazon EC2 images on page 679

676

IBM Cloud Orchestrator 2.4.0.2: User's Guide

IBM SoftLayer
To create a cloud-init-ready image template in SoftLayer, complete the
following steps:
1. From the SoftLayer portal, create an instance SoftLayer-provided base
OS images or create an instance from an existing image template that
needs a cloud-init script installed.
2. To add cloud-init support to the image, follow the procedure in
Adding cloud-init to Linux images on page 336.

3.

4.

5.
6.
7.

Note: If you do not correctly modify the cloud-init configuration file

as specified in the procedure, you cannot access the provisioned virtual
machine anymore.
Download the file http://<pcg_machine>:9797/downloads/scripts/
softlayer/linux/cloud-init/DataSourceSL.py, where <pcg_machine> is
the IP address of the machine where Public Cloud Gateway is installed,
and store the file in the /usr/lib/python2.6/site-packages/cloudinit/
sources directory.
Update the settings.py script in the /usr/lib/python2.6/sitepackages/cloudinit directory. Add SL in the datasource list and
comment out all the others.
When the instance is running, from the SoftLayer portal, access the
computing instance: Device > Device List > Device Name.
From the Device List, select the Computing Instance from actions
menu. Select Create Image Template.
Follow the prompts to create the image template.

Non-IBM OpenStack
Follow the OpenStack descriptions for OpenStack Linux image
requirements. See http://docs.openstack.org/image-guide/content/
ch_openstack_images.html. Ensure that you have added the cloud-init
support to the image.

Creating Workload Deployer cloud images for Linux

You can create cloud-init images for Workload Deployer deployment for Linux.
The image creation is dependent on the target IaaS cloud.
Note: For Workload Deployer deployment, cloud-init version 0.6.0 or later is
required for cloud images.
Amazon AWS EC2 cloud-init images
v Complete the procedure: Creating cloud-init images for Nova
deployment for Linux on page 676 for Amazon AWS EC2 images.
v To enable password base authentication, see Password authentication
on Amazon EC2 images on page 679
Amazon AWS EC2 scp-init images
Complete the procedure: Creating cloud-init images for Nova
deployment for Linux on page 676 for Amazon AWS EC2 images.
Before you capture the image from the provisioned instance, update the
instance by completing these steps:
1. Ensure that the following packages are installed in the instance:
Software prerequisites for Linux images (KVM or VMware
hypervisors) on page 337.
Chapter 8. Managing a hybrid cloud

677

2. Create a supported image on Amazon EC2 for use with IBM Cloud
Orchestrator: Enable Amazon EC2 image for scp-init activation on
page 679.
3.
Note:
v For images used in Virtual System Pattern deployment only:
edit the file /etc/rc.d/rc.local, for Red Hat Enterprise Linux or
edit the file /etc/rc.local for Ubuntu Linux
v Add the line
ip addr add curl -s http://169.254.169.254/latest/meta-data/public-ipv4 dev eth0

v This change enables a successful start of the IBM Tivoli Monitoring

agent. That agent is installed during a Virtual System Pattern
deployment.
To enable password base authentication, see Password authentication on
Amazon EC2 images on page 679
IBM SoftLayer
To create a cloud-init-ready image template in SoftLayer, complete the
following steps:
1. From the SoftLayer portal, create an instance from SoftLayer-provided
base OS images or create an instance from an existing image template
that needs a cloud-init script installed.
2. To add cloud-init support to the image, follow the procedure in
Adding cloud-init to Linux images on page 336.
3. Download the following file to the Linux image: http://
<Workload_Deployer_machine>/downloads/cloud-init/scp-cloud-init
where <Workload_Deployer_machine> is the IP address of the server
where the Workload Deployer component is installed.
4. Run the following commands as the root user:
chmod 755 scp-cloud-init

and
./scp-cloud-init install

5. Create the ovf-env.done file by using the following commands:

mkdir -p /opt/IBM/AE/AR/

and
touch /opt/IBM/AE/AR/ovf-env.done

6. When the instance is running, from the SoftLayer portal, access the
computing instance: Device > Device List > Device Name.
7. From the Device List, select the Computing Instance from actions
menu. Select Create Image Template.
8. Follow the prompts to create the image template.
Non-IBM OpenStack
Follow the OpenStack descriptions for OpenStack Linux image
requirements. See http://docs.openstack.org/image-guide/content/
ch_openstack_images.html. Ensure that you have added the scp-init
support to the image.

678

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Enable Amazon EC2 image for scp-init activation:

Enable root login to Amazon EC2 images
By default, some Amazon EC2 images do not allow you to log in as the root user
and only allow you to log in using the ec2-user user. To log in as the root user,
complete the following steps:
1. Log in to the image by ssh using the ec2-user user and run the following
commands:
sudo cp ~/.ssh/authorized_keys /root/.ssh/authorized_keys

and
sudo service sshd restart

2. Create a supported image on Amazon EC2 for use with IBM Cloud
Orchestrator.
Note: The following instructions are applicable for Linux images only.
Windows images are not supported.
3. Download the following file to the Linux image: http://
<Workload_Deployer_machine>/downloads/cloud-init/scp-cloud-init where
<Workload_Deployer_machine> is the IP address of the server where the
Workload Deployer component is installed.
4. Run the following commands as the root user:
chmod 755 scp-cloud-init

and
./scp-cloud-init install

5. Create the ovf-env.done file by using the following commands:

mkdir -p /opt/IBM/AE/AR/

and
touch /opt/IBM/AE/AR/ovf-env.done

Delete the content of the /etc/rc.d/rc.local file. rc.local is an init script file
provided by Amazon to edit the authentication_keys and sshd_config files. You
must delete the content of the rc.local file to keep your preferences.
7. Select the Create Image option from the Amazon Web Service (AWS)
Management Console to create an image from the instance. For more
information about the AWS Management Console, see https://
console.aws.amazon.com/console/home.
6.

Password authentication on Amazon EC2 images:

You can allow password authentication on Amazon EC2 images.
Usually, Amazon Linux images have password and root login disabled by default.
Amazon AWS EC2 recommends to use SSH keys to access the images. The images
are usually also sudo enabled.
You can enable password and root login using the following procedure:
1. Update the cloud-init configuration file on page 680 to allow root access and
password login.
2. Update the authorized_keys file on page 680.

Chapter 8. Managing a hybrid cloud

679

3. Update the sshd_config file to enable password authentication and root login.
Note: Future Amazon updates to the images might require changes to the
procedure.
Update the cloud-init configuration file
Make sure that the following lines are in the /etc/cloud/cloud.cfg file:
disable_root: false
ssh_pwauth:
true

These properties enable root login and password authentication in cloud-init. They
are required to set the password via user-data.
Update the authorized_keys file
In the authorized_keys file, remove the command prefix and leave only the
ssh-rsa statement. For example, change the following default content:
no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="echo Please login
as the user \"ec2-user\" rather than the user \"root\".;echo;sleep 10"
ssh-rsa <content of sshkey>

to the following content:

ssh-rsa <content of sshkey>

Update the sshd_config file

Log on to the Amazon EC2 image by using SSH and complete the following steps:
1. Edit the /etc/ssh/sshd_config file.
2. Update the following lines:
PasswordAuthentication yes
PermitRootLogin yes

3. Save the file.

4. Run the following command:
sudo service sshd restart

Creating cloud-init images for Nova deployment on Windows

You can create cloud-init images for Nova deployment for Windows.

About this task

The image creation is dependent on the target IaaS cloud.

Procedure
1. IBM SoftLayer
To create a cloud-init-ready image template in SoftLayer, complete the
following steps:
a. Deploy single virtual server from a public image:
1) Select a public image, for example Windows Server 2012 Standard
Edition (64 bit).
2) Flavor: Small.
3) No key.

680

IBM Cloud Orchestrator 2.4.0.2: User's Guide

4) No user/password.
5) No volume attach.
b. Log on to the virtual machine:
1) The virtual machine password will be generated at first. So once the
virtual machine is reported as ACTIVE, open the SoftLayer portal and
navigate to your devices list.
2) Expand the virtual machine you just provisioned and click the show
password box to reveal the administrator password.
3) Use this password to log on to the virtual machine using RDP with the
IP address provided.
4) Depending on the load on the SoftLayer datacenter you are using, it
may take up to 20 minutes before the login information becomes
available.
c. Install cloudbase-init on the virtual machine:
1) Download the installer from https://www.cloudbase.it/downloads/
CloudbaseInitSetup_Beta_x64.msi.
2) Run the installer.
3) Enter the correct administrator user name for your version of Windows.
For example, Administrator for the English version.
4) Make sure you check the use metadata password option.
5) Click next and wait until the installation completes. Do NOT select to
run sysprep or to shut down the virtual machine.
6) Click finish to close the installer.
d. Copy the SoftLayer metadata service to the virtual machine:
1) The built-in version of cloudbase-init does not support loading
metadata from SoftLayer. Therefore the cloudbase-init installation on
your virtual machine must be extended with a small file that
implements a SoftLayer metadata service.
Download from http://<pcg host>:9797/downloads/scripts/softlayer/
windows/cloudbase-init/.
2) Copy slservice.py to the services folder of your cloudbase-init
installation. The default is C:\Program Files (x86)\Cloudbase
Solutions\Cloudbase-Init\Python27\Lib\site-packages\
cloudbaseinit\metadata\services.
3) Adjust the configuration settings of cloudbase-init:
a) Open the file cloudbase-init.conf in an editor. The default is
C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\
conf\cloudbase-init.conf.
b) Make sure it contains these lines:
metadata_services=cloudbaseinit.metadata.services.slservice.SLService
plugins=cloudbaseinit.plugins.windows.setuserpassword.SetUserPasswordPlugin

4) Create a private image from the virtual machine:

a) Leave the virtual machine (do not shut it down, run sysprep or
anything).
b) Go back to the SoftLayer portal and click on the virtual machine to
open its details.
c) In the action menu, select the create image template action and
provide an image name.
d) You can now use this private image for provisioning with IBM
Cloud Orchestrator.
Chapter 8. Managing a hybrid cloud

681

5) (Optional) Delete the original virtual machine:

a) Once the new image has been created, you can safely delete the
original virtual machine using the IBM Cloud Orchestrator UI.
b) Be aware that creating the private image template may take up to 20
minutes depending on the size of the virtual machine.
c) Until the image creation transaction has been completed, the original
virtual machine can not be deleted.
Note: Keep in mind that the password that you enter during
provisioning will be visible to anyone who can log on to the provisioned
virtual machine. So it is best to change the password as soon as possible
after the first login.
Note: Setting the password during provisioning will work only if the
chosen password complies with the password policy of the Windows
operating system on the image. If the password you chose at
provisioning time does not comply with the password policy, the
password will not be set. You will then be able to access the virtual
machine using the password originally generated by SoftLayer which
you can reveal using the SoftLayer portal.
2. Amazon AWS EC2
a. Deploy a single virtual server from a public image:
IBM Cloud Orchestrator will not display public images so you will have to
deploy from the EC2 portal.
Log into the AWS portal, open the EC2 application and go to AMIs. Select the
filter Public Images. Choose an available Windows AMI, for example
Windows_Server-2012-R2_RTM-English-64Bit-Base. Click Launch. Select the
instance flavor. An EBS-only flavor is recommended to save costs, for
example t2.micro.
Go to the next step to configure the instance. Depending on your
requirements you may also want to enable the public IP assignment. Click
Next until you reach the security group configuration. There you must
make sure that you select a security group that allows RDP access to the
virtual machine. Click Review and Launch and then Launch. The initial
administrator password will be generated and encrypted using a Keypair.
Be sure that you select a Keypair that you have access to. For this you need
the private key pem file from the Keypair creation.
b. Log on to the virtual machine:
When the instance appears as running with all status checks done in the EC2
portal, select the instance and click Connect. Click Get Password and select
the pem private key file of the Keypair you selected at provisioning time.
Click download remote desktop file and open it with RDP. Use the
displayed password to connect.
c. Install cloudbase-init on the virtual machine:
Run the installer.
Enter the correct administrator user name for your version of Windows. For
example, Administrator for the English version. Make sure you that you do
not check the use metadata password option as EC2 does not provide
passwords using metadata. Click Next and wait until the installation
completes. Do not select to run sysprep or to shut down the virtual
machine. Click Finish to close the installer.
d. Copy password script to the virtual machine:

682

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The built-in version of cloudbase-init does not support setting the

administrator password for EC2 instances. Also the EC2ConfigService
provided on Amazon does not yet support execution of Python scripts.
Therefore the cloudbase-init installation on your virtual machine has to be
extended with a small file that executes a script to set the password.
Download from http://<pcg host>:9797/downloads/scripts/ec2/windows/
cloudbase-init/. Copy setpasswd_ec2.py to the localscripts folder of
your cloudbase-init installation. The default is: C:\Program Files
(x86)\Cloudbase Solutions\Cloudbase-Init\LocalScripts.
e. Adjust the configuration settings of cloudbase-init:
Open the file cloudbase-init.conf in an editor. The default is: C:\Program
Files (x86)\Cloudbase Solutions\Cloudbase-Init\conf\cloudbaseinit.conf. Make sure it contains this line:
plugins=cloudbaseinit.plugins.windows.localscripts.LocalScriptsPlugin.
f. Adjust the configuration settings of EC2ConfigService:
Run Ec2ConfigServiceSettings. The default is: C:\Program
Files\Amazon\Ec2ConfigService\Ec2ConfigServiceSettings.exe. In the
Image tab make sure that the random option is set for the administrator
password. This enables the option to access the virtual machine through a
Keypair while cloudbase-init will allow access through password.
g. Adjust the service dependencies of cloudbase-init:
Cloudbase-init needs to wait until the Ec2ConfigService is finished before
it can set the administrator password. Therefore the service dependencies of
cloudbase-init have to be adjusted. As the administrator user, open a
command shell. Run the command:
sc config cloudbase-init depend=Winmgmt/Ec2Config

h. Create a private image from the virtual machine:

Leave the virtual machine (do not shut it down, run sysprep or anything).
Go back to the EC2 portal and click on the virtual machine to open its
details. In the action menu, select the create image action and provide an
image name. You can now use this private image for provisioning with IBM
Cloud Orchestrator.
i. (Optional) Delete the original virtual machine:
Once the new image has been created you can safely delete the original
virtual machine using the IBM Cloud Orchestrator UI. Be aware that creating
the private image template may take up to 20 minutes depending on the size
of the virtual machine. Until the image creation transaction has been
completed, the original virtual machine cannot be deleted.
Note: Keep in mind that the password that you enter during provisioning
will be visible to anyone who can log on to the provisioned virtual machine.
So it is best advised to change the password as soon as possible after the
first login.
Note: Setting the password during provisioning will work only if the chosen
password complies with the password policy of the Windows operating
system on the image. If the password you chose at provisioning time does
not comply with the password policy, the password will not be set. If you
chose to use a Keypair for accessing the virtual machine in addition to a
password, you will still be able to connect to the virtual machine by using
your private key to decrypt the password on the AWS portal.

Chapter 8. Managing a hybrid cloud

683

Creating Workload Deployer cloud images for Windows on

Softlayer
To create an scp-cloud-init image template to be used for vSysClassic patterns in
Softlayer, complete the following steps.

Procedure
1. Deploy a single virtual server from a public image:
Select a public image, for example Windows Server 2012 Standard Edition (64
bit), Flavor: Small, No key, No user/pwd, No volume attach.
2. Log on to the virtual machine:
The virtual machine password will be generated at first. So once the virtual
machine is reported as ACTIVE, open the SoftLayer portal and navigate to your
devices list. Expand the virtual machine you just provisioned and click show
password to reveal the Administrator password. Use this password to log on to
the virtual machine using RDP with the IP address provided. Depending on the
load on the SoftLayer datacenter you are using, it may take up to 20 minutes
before the login information becomes available.
3. Adjust Firewall and User Account Control:
To make the image accessible to Workload Deployer follow the section for the
Windows operating version chosen in step 1 described here:
http://www-01.ibm.com/support/knowledgecenter/api/content/
SS4KMC_2.3.0/com.ibm.sco.doc_2.3/scenarios/
c_prereq_kvm_vmware_images_win.html.
4. Install the prerequisite software, as described here: Software prerequisites for
Microsoft Windows images on page 338.
5. Install the scp-cloud init scripts:
Download the following files:
http://<Workload_Deployer_machine>/downloads/cloud-init/scp-cloud-init.cmd
http://<Workload_Deployer_machine>/downloads/cloud-init/scp-cloud-init.vbs

Copy the scp-cloud-init.* files to the directory c:\windows\setup\ibm (create

the directory if it does not exist).
6. Copy activation and password script to the virtual machine:
http://<pcg_machine>:9797/downloads/scripts/ec2/windows/scp-cloud-init/AE.bat
http://<pcg_machine>:9797/downloads/scripts/ec2/windows/scp-cloud-init/setpasswd_sl_scp.py

Copy the files to the directory c:\windows\setup\ibm. Add one script to run
when starting the virtual machine by using the group policy editor:
v Run gpedit.msc.
v In the Local Group Policy Editor window, select Computer Configuration >
Windows Settings > Scripts (Startup/Shutdown).
v In the right pane, double-click Startup.
v In the Startup Properties window, click Add.
v In the Add a Script window, enter c:\windows\setup\ibm\
setpasswd_sl_scp.py in the Script Name field, and click OK.
v Click OK to save your changes and close the Startup Properties window.
v Close the Local Group Policy Editor window.
7. Create a private image from the virtual machine:
Leave the virtual machine (do not shut it down, run sysprep or anything). Go
back to the SoftLayer portal and click on the virtual machine to open its details.

684

IBM Cloud Orchestrator 2.4.0.2: User's Guide

In the action menu select the create image template action and provide an
image name. You can now use this private image for provisioning with IBM
Cloud Orchestrator.
8. (Optional) Delete the original virtual machine:
Once the new image has been created you can safely delete the original virtual
machine using the IBM Cloud Orchestrator UI. Be aware that creating the
private image template may take up to 20 minutes depending on the size of the
virtual machine. Until the image creation transaction has been completed, the
original virtual machine can not be deleted.
Note: Keep in mind that the password that you enter during provisioning will
be visible to anyone who can log on to the provisioned virtual machine. So it is
best advised to change the password as soon as possible after the first logon.
Note: Setting the password during provisioning will work only if the chosen
password complies with the password policy of the Windows operating system
on the image. If the password you chose at provisioning time does not comply
with the password policy, the password will not be set. You will then be able to
access the virtual machine using the password originally generated by
SoftLayer which you can reveal using the SoftLayer portal.

Creating Workload Deployer cloud images for Windows on EC2

To create a scp-cloud-init image template to be used for vSysClassic patterns in
EC2, complete the steps described in this topic.

Procedure
1. Deploy single virtual server from a public image.
IBM Cloud Orchestrator will not display public images so you will have to
deploy from the EC2 portal. Log into the AWS portal, open the EC2 application
and go to AMIs.
Select the filter Public Images. Choose an available Windows AMI, for example
Windows_Server-2012-R2_RTM-English-64Bit-Base. Click Launch. Select the
instance flavor. An EBS-only flavor is recommended to save costs, for example
t2.micro. Go to the next step to configure the instance. Depending on your
requirements you may also want to enable the public IP assignment. Click Next
until you reach the security group configuration. There you must make sure
that you select a security group that allows RDP access to the virtual machine.
Click Review and Launch and then Launch. The initial administrator password
will be generated and encrypted using a Keypair. Be sure you select a Keypair
that you have access to. For this you need the private key pem file from the
Keypair creation.
2. Log on to the virtual machine.
When the instance appears as running with all status checks done in the EC2
portal, select the instance and click Connect. Click Get Password and select the
pem private key file of the Keypair that you selected at provisioning time. Click
download remote desktop file and open it with RDP. Use the displayed
password to connect.
3. Adjust Firewall and User Account Control.
To make the image accessible to Workload Deployer follow the section for
Windows operating version chosen in Step 1, described here:
http://www-01.ibm.com/support/knowledgecenter/api/content/
SS4KMC_2.3.0/com.ibm.sco.doc_2.3/scenarios/
c_prereq_kvm_vmware_images_win.html.

Chapter 8. Managing a hybrid cloud

685

4. Install the prerequisite software, as described here: Software prerequisites for

Linux images (KVM or VMware hypervisors) on page 337.
5. Install the scp-cloud init scripts by downloading the following files:
http://<Workload_Deployer_machine>/downloads/cloud-init/scp-cloud-init.cmd
http://<Workload_Deployer_machine>/downloads/cloud-init/scp-cloud-init.vbs

6. Copy the activation and password script to the virtual machine:

http://<pcg_machine>:9797/downloads/scripts/ec2/windows/scp-cloud-init/AE.bat
http://<pcg_machine>:9797/downloads/scripts/ec2/windows/scp-cloud-init/setpasswd_ec2_scp.py

Copy the files to the directory c:\windows\setup\ibm. Add one script to run
when starting the virtual machine by using the group policy editor: run
gpedit.msc. In the Local Group Policy Editor window, select Computer
Configuration > Windows Settings > Scripts (Startup/Shutdown). In the right
pane, double-click Startup. In the Startup Properties window, click Add. In the
Add a Script window, enter c:\windows\setup\ibm\setpasswd_ec2_scp.py in
the Script Name field, and click OK. Click OK to save your changes and close
the Startup Properties window. Close the Local Group Policy Editor window.
7. Run Ec2ConfigServiceSettings. Default: C:\Program Files\Amazon\
Ec2ConfigService\Ec2ConfigServiceSettings.exe. In the Image tab make sure
the keep existing option is set for the administrator password. We want the
password to be set by cloudbase-init, not by Ec2ConfigService.
8. Create a private image from the virtual machine. Leave the virtual machine (do
not shut it down, run sysprep or anything). Go back to the EC2 portal and click
on the virtual machine to open its details. In the action menu select the create
image action and provide an image name. You can now use this private image
for provisioning with IBM Cloud Orchestrator.
9. (Optional) Delete the original virtual machine. Once the new image has been
created you can safely delete the original virtual machine using the IBM Cloud
Orchestrator UI. Be aware that creating the private image template may take up
to 20 minutes depending on the size of the virtual machine. Until the image
creation transaction has been completed, the original virtual machine can not be
deleted.
Note: Keep in mind that the password that you enter during provisioning will
be visible to anyone who can log on to the provisioned virtual machine. So it is
best advised to change the password as soon as possible after the first login.
Note: Setting the password during provisioning will work only if the chosen
password complies with the password policy of the Windows operating system
on the image. If the password you chose at provisioning time does not comply
with the password policy, the password will not be set. Since EC2 cannot
decrypt the password again as in the case of the public image, it is best advised
to change the password first to a known value or to add a second user with
known credentials before creating the private image.

686

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Tagging images with the configuration strategy

After an image is created, you must set the configuration strategy for an image,
either on the image or at the region level.
The configuration strategy describes if the image has a cloud-init or scp-init
activation style configuration.
The target environments, Amazon EC2, SoftLayer, , and non-IBM-OpenStack
(NIOS) have different capabilities to attach the configuration strategy on images.
These are the possibilities for image configuration strategy:
cloud-init
New type introduced with IBM Cloud Orchestrator V2.4.
scp-init
Existing type supported in SmartCloud Orchestrator V2.3.
If the image configuration strategy is not defined on the image, the image returns
the configuration strategy as defined in the ImageType property in the config.json
file. For more information, see Table 90 on page 706.
If the image has a configuration strategy defined and the region has an ImageType
property, the configuration strategy on the image has precedence. If the image does
not have a configuration strategy defined and the region has an ImageType
property, the image returns the ImageType value defined on the region level. If the
region does not have an ImageType property and a configuration strategy is not
defined on the image, then scp-init is used by default.
To define the configuration strategy on an image, see the following procedures
depending on the target environment:
Amazon EC2
Amazon EC2 has the capability to apply tags to images. A tag is a
key/value pair which is stored with the image meta data. To control the
configuration strategy in Amazon EC2, there is a tag named ImageType
which can have a value of cloud-init or scp-init.
SoftLayer
Configuration strategy is defined as part of the region configuration in the
config.json file using the ImageType property on the region definition. In
addition, SoftLayer allows setting a tag on the image itself using the
SoftLayer management portal. Possible tag values are cloud-init or
scp-init.
As an alternative to tagging images using the SoftLayer management
portal, you can tag images using the following REST API call (on one line):
curl -u $userId:$apiAccessKey -X POST -d {"parameters":["<tag-value>"]}
https://api.softlayer.com/rest/v3/SoftLayer_Account/PrivateBlockDeviceTemplateGroups/
<image-template-global-identifier>/setTags.json

Note:
v SoftLayer does not support to set tag value during image template
creation. It first requires creating the template and then editing the
template by using templateID.
v In SoftLayer, tags on images only work within the account where the
image resides. If an image is shared across accounts, the image tag is not
Chapter 8. Managing a hybrid cloud

687

visible in the consuming accounts. Therefore, in the consuming accounts,

an ImageType property in the region definition must be used or the
image must be copied to the target account.
Non IBM OpenStack (NIOS)
For NIOS it is not supported to configure configuration on a per image
base. Configuration strategy is defined as part of the region configuration
in the config.json file.
Region level ImageType definition
The Public Cloud Gateway supports an ImageType property on the region
definition. The ImageType property controls the configuration strategy
returned for the images within this region. The ImageType property works
as a default value for all images which do not have a defined configuration
strategy.

Configuring flavors
OpenStack API requires flavors for provisioning virtual machines. IBM Cloud
Orchestrator must be able to return a flavor list for each region.
The Public Cloud Gateway stores the current list of known flavors in the
flavors.json file on Central Server 2 in the /opt/ibm/pcg/etc directory.
The following capabilities are supported:
v A global flavor list provided by the default section, if no remote cloud or region
specific information is provided.
v A remote cloud type specific default flavor provided through the following
sections:
ec2_default
nios_default
softlayer_default
All the flavor definitions within the flavors.json file must be valid for the related
remote cloud regions. All the definitions in these sections are snippets and provide
configuration examples.
Note:
v Changes to the flavors.json file are only active after restarting the Public Cloud
Gateway.
v Failure to the above assumptions result in provisioning errors.
v A flavor must not be removed if virtual machines with this flavor exist.

Amazon AWS EC2

Amazon AWS EC2 only supports a predefined list of flavors published on their
website. The Public Cloud Gateway supplies a current list in the flavor.json file
under the ec2_default section. This hardcoded list can be extended or corrected
based on the changes Amazon AWS EC2 provides. See http://aws.amazon.com/
ec2/instance-types/.
The following rules apply for Amazon AWS EC2:
v You can modify the global list supplied in the ec2_default section. This affects
all Amazon AWS EC2 regions except the ones that have a separate named
section.

688

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v You can add a new section for the specific Amazon AWS EC2 region with the
name because this region is defined in the config.json file.
Note: With the Amazon AWS EC2 API, you cannot query or manage the
supported flavors. Any changes to the list of flavors for Amazon AWS EC2 must
match the published list on their website or the list of flavors shown in the
Amazon AWS EC2 management UI. Otherwise, the virtual machine has
provisioning errors.

non-IBM supplied OpenStack

non-IBM supplied OpenStack is managed with the OpenStack EC2 provider. You
cannot query or manage flavors. A manual step is required to synch and match the
flavors available in each non-IBM supplied OpenStack region with the
flavors.json file. If the detail of the flavors is later changed, the file must be
updated again and the Public Cloud Gateway must be restarted.
The following rules apply for non-IBM supplied OpenStack:
v You can modify the global list supplied in nios_default section. This affects all
non-IBM supplied OpenStack regions except the ones that have a separate
named section.
v You can add a new section for the specific non-IBM supplied OpenStack region
with the name because this region is defined in the config.json file.
1. To obtain the list of flavors that are supported on a particular non-IBM
supplied OpenStack region, log on to a Nova node in that region and issue the
command:
nova flavor-list

The following is an example of the response:

root@nio3:~# nova flavor-list
OS Password:
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+-------------+
| ID | Name
| Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public | extra_specs |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+-------------+
| 1 | m1.small | 2048
| 20
| 0
|
| 1
| 1.0
| True
| {}
|
| 2 | m1.medium | 4096
| 40
| 0
|
| 2
| 1.0
| True
| {}
|
| 3 | m1.large | 8192
| 80
| 0
|
| 4
| 1.0
| True
| {}
|
| 4 | m1.xlarge | 16384
| 160 | 0
|
| 8
| 1.0
| True
| {}
|
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------+-------------+

2. Edit the file /opt/ibm/pcg/etc/flavors.json file on the Central Server 2 node

and use the data from the Name, Memory_MB, Disk, and VCPUs columns to
populate the name, RAM, disk, and CPU fields. Different flavors can be defined
for each non-IBM supplied OpenStack and SoftLayer region. The region names
must exactly match those defined in the config.json file.
3. There are default sections in this file where you can provide global defaults.
The following possibilities are available:
default
The global default independent of the cloud type: SoftLayer or
non-IBM supplied OpenStack.
nios_default
A global default for non-IBM OpenStack regions.
softlayer_default
A global default for SoftLayer regions.
4. If the output in the previous step was generated in a non-IBM supplied
OpenStack region that is defined as nioRegion1 in the config.json file, the
resulting flavors.json would look similar to this:
Chapter 8. Managing a hybrid cloud

689

"nioRegion1": {
"m1.small": {"name":"Small", "cpu":1, "ram":2048, "disk":20},
"m1.medium": {"name":"Medium", "cpu":2, "ram":4096, "disk":40},
"m1.large": {"name":"Large", "cpu":4, "ram":8192, "disk":80},
"m1.xlarge": {"name":"Extra Large", "cpu":8, "ram":16384, "disk":160},
}
}

Using this example, when accessing nioRegion1, IBM Cloud Orchestrator offers
a list of four flavors, but any other non-IBM supplied OpenStack regions offers
the six flavors that are defined for the default region.
Note:
v The ID in the flavors.json file, m1.small, must match the flavor name on
non-IBM supplied OpenStack and not the flavor ID.
v IBM Cloud Orchestrator requires at least 512 MB of memory to be defined in
flavors.

IBM SoftLayer
SoftLayer does not support flavors during deployment. The flavors.json defines
the set of flavors that you can use during deployment by using IBM Cloud
Orchestrator. SoftLayer only supports a certain list of possible values for CPU,
RAM, and disk. These values can change over time. The possible values are visible
if you try to create a cloud compute instance through the SoftLayer provided
management UI. Only these values can be used for flavor definitions. If other
values are used, you might receive deployment errors.
The following rules apply for IBM SoftLayer:
v You can modify the global list supplied in softlayer_default section. This
affects all IBM SoftLayer regions except the ones that have a separate named
section.
v You can add a new section for the specific IBM SoftLayer region with the name
because this region is defined in the config.json file.
Note:
v IBM Cloud Orchestrator requires at least 512 MB of memory to be defined in
flavors.
v SoftLayer provides a predefined set of values for CPU, RAM, and disk. Check
the possible values in the SoftLayer documentation or in the SoftLayer
management portal.

Configuring quotas
You can configure quotas.

Configuring default quota support

There are two types of quota definitions in the Public Cloud Gateway:
v A default quota set that is used if no project level quotas are defined.
v Project specific quotas.
Quotas are on a per project per region level.

690

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The default quotas setting is stored within the config.json file located in the
/opt/ibm/pcg/etc subdirectory under the Central Server 2 where the Public Cloud
Gateway component is installed.
The file is in JSON format. This is the quota section of the file:
{
"defaultQuota":{
"instances":"100",
"cores":"100",
"ram":"262144",
"gigabytes":"512",
"volumes":"2048",
"key_pairs":"100"
}
}

To modify the config.json file, as root, open it in a text editor and change the
values:
1. Connect to Central Server 2 via SSH. Default location: /opt/ibm/pcg/etc/
config.json.
2. Restart the Public Cloud Gateway by submitting the following command as
root on the Central Server 2 command line: service pcg restart.

Configuring project quota

Project quotas are managed via the Administration UI (Horizon). For information,
see:
v Editing the domain quotas on page 263
v Configuring project quotas on page 268
Note: Project quotas cannot be deleted from the Administration UI. They can only
be created and modified. The Public Cloud Gateway only supports a subset of the
quotas as described in Quota support overview on page 669.

Configuring caching
Account caching management with external clouds is required as the remote
clouds have denial of service and API rate limits management in place.
Note: The previous capability of cacheCounters in config.json located in the
/opt/ibm/pgc/etc directory is deprecated and no longer supported. See
Upgrading from SmartCloud Orchestrator V2.3 or V2.3.0.1 on page 147.
Both are configured within the config.json files in different sections.
The cache values describe when the public cloud internal caches are refreshed if no
modifying resource requests are performed. Modifying resources requests are
create / modify / delete style requests.
A modifying request would invalidate the caches for the triggering URL (region /
project).
The values must be adapted so that the least amount of API calls are done against
the remote clouds without impacting the responsiveness of the Public Cloud
Gateway.
Caching of resources:
Chapter 8. Managing a hybrid cloud

691

{
"cacheTimeout":{
"serversTimeout":"180",
"glanceImagesTimeout":"180",
"availabilityZoneTimeout":"180",
"volumesTimeout": "180",
"keypairTimeout": "180"
}
}

All values are in seconds.

serversTimeout
Defines the cache refresh interval for virtual machine instance related data.
glanceImagesTimeout
Defines the cache refresh interval for image related data. For example, if
you add a new image to the IaaS, this is the time until it shows up in a
"glance image-list" for that region.
availabilityZoneTimeout
Defines the cache refresh interval for changes related to availability-zones.
Changes are normally infrequent because a new datacenter is added by the
IaaS provider or a new region is defined in NIOS.
volumesTimeout
Defines the cache refresh interval for volume related data.
keypairTimeout
Defines the cache refresh interval for key pair related data.
Caching of quota actuals:
{
QuotaTimeouts
{
"quotaTimeout":{
"serverQuotaTimeout":"600",
"volumeQuotaTimeout":"600",
"keypairQuotaTimeout":"600"
}
}
}

All values are in seconds. Each entry defines a refresh interval for the quota
calculation:
serverQuotaTimeout
Defines the refresh interval in seconds for virtual machine instance related
quota elements.
volumeQuotaTimeout
Defines the refresh interval in seconds for volume related quota elements.
keypairQuotaTimeout
Defines the refresh interval in seconds for key pair related quota elements.

692

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Changing the Keystone administrator password

You can change the Keystone administrator password. There are two scenarios for
doing so in the Public Cloud Gateway.
First scenario:
The Keystone administrator password is changed. Public Cloud Gateway
stores the credentials to logon to Keystone in the admin.json file
(/opt/ibm/pcg/etc):
{
"auth":
{ "passwordCredentials":
{
"username":"xxxx",
"password":"yyyyy"
},
"tenantName":"zzzz",
"domainName": "ddddd"
}
}

The password is encrypted using the encryptPassword.sh located in the

/opt/ibm/pcg directory (refer to Command-line interface scripts on page
715 and Failure to generate admin token on page 1066).
Second scenario:
The password to access a remote cloud is changed. The access information
to the remote clouds is stored in the credentials.json file in the
/opt/ibm/pcg/etc directory.
For Amazon AWS EC2, refer to: Configuring the Public Cloud Gateway
for Amazon EC2 on page 697.
For SoftLayer, refer to: Configuring the Public Cloud Gateway for
SoftLayer on page 703.
For non-IBM supplied OpenStack (NIOS), refer to: Configure non-IBM
supplied OpenStack EC2 credentials on page 711.
The password is encrypted using the encryptPassword.sh located in the
/opt/ibm/pcg directory. Refer to: Command-line interface scripts on page
715.

Changing a region name

You can change a region name.
Go to the /opt/ibm/pcg/etc directory in Central Server 2 and open the
config.json property file. Replace the old name with new one.
For example, to show the change of the region name from EC2-001 to EC2region for
an EC2 region. The original EC2 region is:
"ec2":[
{
"name":"EC2-001",
"url":"https://ec2.us-east-1.amazonaws.com/",
"enabled":true
}

Change the region name:

Chapter 8. Managing a hybrid cloud

693

"ec2":[
{
"name":"EC2region",
"url":"https://ec2.us-east-1.amazonaws.com/",
"enabled":true
}

Configure IBM Cloud Orchestrator for the new region and remove the entry for
the old region as documented below.
Restart the Public Cloud Gateway by using the service pcg restart command.
For more information about starting the Public Cloud Gateway, see
Command-line interface scripts on page 715.
Delete the services of the old region from keystone:
[root@central-server-2 ~]# source ~/keystonerc
[root@central-server-2 ~]# keystone endpoint-list
+----------------------------------+----------|
id
|
region
+----------------------------------+----------| 0ff9e584b3d04c56af32e7b43ad5324d | EC2-001
| 11924c78eca949ae939f2309a4e21bf9 | EC2-001
| 187dbc8c68b74d5f8e098d4c61544d0b | RegionOne
| 19ded8422da445a7b6ceb0ce6d3c5f5e | RegionOne
| 311e7c36c6b84ee3a5e2f39a04001481 | RegionOne
| 3d8ff61f86f64838be5000b7efd60b89 | RegionOne
| 7f5a578d80684fcaaa473c9012ba7f46 | EC2-001
| bf8de63072ae453fb5ddf8b3027945cf | RegionOne
| e0a8c3d7c821424e94a0ef17c8c1a383 | EC2-001
+----------------------------------+----------+--------------------------------------------------------|
publicurl
+--------------------------------------------------------|
http://central-server-2:5000/v3
| http://central-server-2:9797/EC2-001/v1/%(tenant_id)s
|
http://central-server-2:8776/v1/%(tenant_id)s
|
http://central-server-2:8774/v2/%(tenant_id)s
| https://192.0.2.129:9443/ImageLibrary/ImageService/v1
|
http://central-server-2:9292/
| http://central-server-2:9797/EC2-001/v2.0/%(tenant_id)s
|
http://central-server-2:5000/v3
|
http://central-server-2:9797/EC2-001/v2.0
+--------------------------------------------------------+--------------------------------------------------------|
internalurl
+--------------------------------------------------------|
http://central-server-2:5000/v3
| http://central-server-2:9797/EC2-001/v1/%(tenant_id)s
|
http://central-server-2:8776/v1/%(tenant_id)s
|
http://central-server-2:8774/v2/%(tenant_id)s
| https://192.0.2.129:9443/ImageLibrary/ImageService/v1
|
http://central-server-2:9292/
| http://central-server-2:9797/EC2-001/v2.0/%(tenant_id)s
|
http://central-server-2:5000/v3
|
http://central-server-2:9797/EC2-001/v2.0
+--------------------------------------------------------+---------------------------------------------------------+----------------------------------+
|
adminurl
|
service_id
|
+---------------------------------------------------------+----------------------------------+
|
http://central-server-2:35357/v3
| 40a0d00ad6d34cfc8a5c412c61cb3e33 |

694

IBM Cloud Orchestrator 2.4.0.2: User's Guide

| http://central-server-2:9797/EC2-001/v1/%(tenant_id)s | 372311fb67564e41987038d587c6a539 |
|
http://central-server-2:8776/v1/%(tenant_id)s
| 372311fb67564e41987038d587c6a539 |
|
http://central-server-2:8774/v2/%(tenant_id)s
| b6155b46d8d1463185fdfbddb05f18b5 |
| https://192.0.2.129:9443/ImageLibrary/ImageService/v1
| ac8c99aa1fb445898f92fd0aeb43c8e1 |
|
http://central-server-2:9292/
| 1f3d30e2fcf04bdd908969a987722acc |
| http://central-server-2:9797/EC2-001/v2.0/%(tenant_id)s | b6155b46d8d1463185fdfbddb05f18b5 |
|
http://central-server-2:35357/v3
| 40a0d00ad6d34cfc8a5c412c61cb3e33 |
|
http://central-server-2:9797/EC2-001/v2.0
| 1f3d30e2fcf04bdd908969a987722acc |
+---------------------------------------------------------+----------------------------------+

Delete all the endpoints related for the old region EC2-001 with the following
example command:
[root@central-server-2 ~]# keystone endpoint-delete 0ff9e584b3d04c56af32e7b43ad5324d

Restarting the Public Cloud Gateway

You might need to restart the Public Cloud Gateway.
The Public Cloud Gateway runs as a service on Central Server 2. Some
configuration tasks require a restart of the Public Cloud Gateway to activate
changes:
v Changing a region name
v Changing a keystone administrator password
v Configuring caching
v Configuring default quotas
v Changing flavors
v Changing region settings
To restart the Public Cloud Gateway, complete the following steps:
1. Log on to Central Server 2 as root using SSH.
2. Check if the Public Cloud Gateway is running by executing as root: service
pcg status.
3. Restart the Public Cloud Gateway by executing as root: service pcg restart.
4. Check the log of the Public Cloud Gateway for any errors and exceptions: less
/var/log/pcg/pcg.log.

Remote Cloud API proxy configuration

The Public Cloud Gateway requires connectivity to the remote cloud API
endpoints for Amazon AWS EC2 and SoftLayer.
There are scenarios were no direct connection to the internet from Central Server 1
is available.
The Public Cloud Gateway provides the capability to specify a proxy server within
the config.json file.
It
v
v
v
v

is possible to define:
A default proxy server.
A proxy server for Amazon EC2.
A proxy server for SoftLayer.
A proxy server for non-IBM supplied OpenStack.

Chapter 8. Managing a hybrid cloud

695

There is a new main section in the config.json file in the etc directory of the
Public Cloud Gateway. This is sample content to describe the structure and
properties of the configuration :
"proxy":{
"default":{
"host":"proxy.local",
"port":"3128",
"userid":"xxxxx",
"password":"yyyyy"
},
"nios":{
"host":"localhost",
"port":"3128",
"userid":"xxxxx",
"password":"yyyyy"
},
"ec2": {
"host":"localhost",
"port":"3128"
},
"softlayer":{
"host":"127.0.0.1",
"port":"9090",
"userid":"xxxxx",
"password":"yyyyy"
}
},

The default entry within the proxy definition defines the default proxy. This
definition will be used if there is no proxy definition for the specific remote cloud
type:
v The nios entry defines the specific proxy for all regions of type non-IBM
supplied OpenStack (nios).
v The ec2 entry defines the specific proxy for all regions of type Amazon AWS
EC2 (ec2).
v The softlayer entry defines the specific proxy for all regions of type SoftLayer
(softlayer).
Table 84. Parameters that are used in the proxy definition in the config.json file

696

Parameter

Description

host

This is a required parameter. It is the

hostname or IP address of the proxy server.
Note: If a hostname is provided, it is
required that the hostname can be resolved
to an IP address.

port

This is a required parameter. It is the port on

the host were the proxy server is reachable.
The standard port is 3128 in many proxy
implementations.

userid

This is an optional parameter. If specified, it

specifies the userid which must be used to
contact the proxy server.
Note: If a userid is specified, the password
property is required.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 84. Parameters that are used in the proxy definition in the config.json
file (continued)
Parameter

Description

password

This is a optional parameter. If specified, it

specifies the password which must be used
to contact the proxy server. The value of the
parameter must be encrypted with the
encryptPassword.sh. The encrypted value
must be specified as the value of this
parameter.
Note: If a password is provided, the userid
property is required.

Limitations for Amazon EC2 and non-IBM supplied OpenStack

v Amazon EC2 provides only http or https proxy support.
v The capabilities are limited to the support within the Amazon java client
binding in version 1.5.8.

Limitation for SoftLayer

v Only http or https proxy support is available.

Managing Amazon EC2 using the Public Cloud Gateway

The Public Cloud Gateway is not preconfigured for use with Amazon Elastic
Compute Cloud (Amazon EC2) as part of the IBM Cloud Orchestrator. You must
complete certain configuration tasks before using the Public Cloud Gateway.
1. Familiarize yourself with the Public Cloud Gateway. See Public Cloud
Gateway overview on page 661.
2. Check that prerequisites are met. See Prerequisites on page 675.
3. Configure the Public Cloud Gateway for Amazon EC2. See Configuring the
Public Cloud Gateway for Amazon EC2.
4. Create a supported image. See Creating a supported image on page 676.
5. Configure quotas. See Configuring quotas on page 690.
For information about post-configuration steps, see Performing post-configuration
tasks on page 714.

Configuring the Public Cloud Gateway for Amazon EC2

You can configure the Public Cloud Gateway for Amazon EC2.
There are some configuration steps required in the following files to add a region
and configure the credentials for a project:
v config.json
v credentials.json
Note: The examples shown in this section are only pieces of the config.json and
credentials.json files required for Amazon EC2-specific configurations. Both files
contain additional sections that you must not modify or delete as part of the
Amazon EC2 configuration.

Chapter 8. Managing a hybrid cloud

697

Configure regions in the config.json file

Go to the /opt/ibm/pcg/etc directory and open the config.json file.
The following code of the config.json file is relevant for the Amazon EC2 region
configuration:
{
"vcenters":{
"ec2":[
{
"name":"EC2-US-EAST-NORTHERN-VIRGINIA",
"url":"https://ec2.us-east-1.amazonaws.com",
"enabled":true
},
{
"name":"EC2-US-WEST-OREGON",
"url":"https://ec2.us-west-2.amazonaws.com",
"enabled":false
},
{
"name":"EC2-US-WEST-NORTHERN-CA",
"url":"https://ec2.us-west-1.amazonaws.com",
"enabled":false
},
{
"name":"EC2-EU-IRELAND",
"url":"https://ec2.eu-west-1.amazonaws.com",
"enabled":false
},
{
"name":"EC2-AP-SINGAPORE",
"url":"https://ec2.ap-southeast-1.amazonaws.com",
"enabled":false
},
{
"name":"EC2-AP-TOKYO",
"url":"https://ec2.ap-northeast-1.amazonaws.com",
"enabled":false
},
{
"name":"EC2-AP-SYDNEY",
"url":"https://ec2.ap-southeast-2.amazonaws.com",
"enabled":false
},
{
"name":"EC2-SA-SAOPAULO",
"url":"https://ec2.sa-east-1.amazonaws.com",
"enabled":false
}
],
}
}

The cloud region configuration is described in the vCenters section. Each region is
specified using three key-value pairs: name, url, and enabled.
The parameters in the config.json file are explained in the following table. Update
the enabled parameter to true if you want to specify that a particular region must
be created in Keystone.

698

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 85.
Parameter

Description

name

Name of the region as it appears in

keystone.

url

Amazon EC2: The URL of the Amazon EC2

vCenter that must be associated with the
region. Default Amazon EC2 endpoints are
defined. The data center is part of the URL.
For example, https://ec2.ap-southeast2.amazonaws.com, where ap-sourtheast-2 is
the Amazon data center.

enabled

Amazon EC2: Set to true if that data center

is to be made available to the users of IBM
Cloud Orchestrator. Set to false if that data
center is not available. Do not use quotation
marks.

Note: You must add a mapping for the project of the cloud administrator to the
credentials.json file. The default is admin. If this entry is missing, you cannot add
the availability zone to the domain through the IBM Cloud Orchestrator
Administration UI.
{
"tenantName":"admin",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
},

where xxx is a valid set of credentials to access your Amazon EC2 account.
Additional properties for Amazon EC2 on the region level. Example for
SAOPAULO region:
{
"name":"EC2-SA-SAOPAULO",
"url":"https://ec2.sa-east-1.amazonaws.com",
"enabled":false / true,
"ImageType" : "cloud-init" or "scp-init",
}
Table 86.
Parameter

Description

ImageType

Defines on a region level what image

activation type must be returned for images.
The value is only used for images which are
not already tagged with a image type. See
Tagging images with the configuration
strategy on page 687.

If your account does support the capability to place virtual machines into distinct
subnets of a non-default VPC, there are two properties to control that placement:
Table 87.
Parameter

Description

vpc

The ID of the configured non-default VPC

where the virtual machines are placed.

Chapter 8. Managing a hybrid cloud

699

Table 87. (continued)

Parameter

Description

privateNetworkOnly

Controls whether the machines get a public

IP address. Valid values are true or false. If
true, the virtual machine has no public IP
address, otherwise it gets a public IP
address from an Amazon AWS EC2
provided pool. If the property is not set in
the region definition, the default is false. The
property is supported in case of DefaultVPC
and non-default VPC.

This capability is available when the only supported platform for you account is
VPC. It is not enabled when other supported platforms are listed, for example,
EC2. You can check the supported platform of your account on the EC2 dashboard
in the Account Attributes section.
Be aware that in addition to the configuration in this file, more configuration tasks
are necessary in your Amazon VPC account to leverage the non-default VPC
support. See Configuring subnets and security groups in a non-default VPC
region on page 702.
Configure cloud credentials in the /opt/ibm/pcg/etc/credentials.json file: This
file is used to specify Amazon EC2 credentials for each project. For more
information about defining projects, see Managing projects on page 265. The
Amazon EC2 credentials are mapped to specific projects in IBM Cloud
Orchestrator. These mappings are specified in the credentials.json configuration
file.
Go to the /opt/ibm/pcg/etc directory and open the credentials.json file:
{
"cred":{
"ec2":[
{
"tenantName":"demo",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
},
{
"tenantName":"admin",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
},
{
"tenantID":"xxxxxx",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
},
{
"tenantName":"*",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
}
]
}
}

The parameters in the credentials.json file are explained in the following table.
Update these parameters if you want to specify credentials to project mappings
and define which credentials must be used for the different projects specified.

700

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 88.
Parameter

Description

tenantName

tenantName specifies the OpenStack project

entity, also known as tenant. The following
options to identify a project exist:
v OpenStack project ID.
v OpenStack project name.
v Wildcard * to match any project.
Note: Due to multi-domain support, a
project name might not be unique, therefore
a project ID must be used. To get the project
ID, use the Administrative UI (Horizon)
identity section.

access_key_ID

This is the Amazon EC2 access key for the

project.

secret_access_key

This is the Amazon EC2 secret access key

used for the project. This value must be
encoded using the encryptpassword.sh
script that is available in the ../opt/ibm/pcg
directory.

region

This parameter specifies the region name as

defined in the config.json file. The region
parameter is optional. If this parameter is
set, the mapping is restricted to this specific
region. If it is not set, the mapping is valid
for all regions defined for the specific cloud
type in the config.json file.
Replace yyy in the example below with the
value of the name parameter as it is defined
in the config.json file. Example statement:
{
"tenantName":"*",
"region": "yyy",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
}

Note: You must add a mapping for the project of the cloud administrator to the
credentials.json file. The default is admin. If this entry is missing, you cannot add
the availability zone to the domain using the Administration user interface:
{
"tenantName":"admin",
"region": "yyy",
"access_key_ID":"xxx",
"secret_access_key":"xxx"
},

where xxx is a valid set of credentials to access your Amazon AWS EC2 account.
Procedure to activate configuration changes:
1. Restart the Public Cloud Gateway by using the pcg restart command. For
more information, see Command-line interface scripts on page 715.

Chapter 8. Managing a hybrid cloud

701

2. Execute the script refreshEndpoint.sh in the /opt/ibm/pcg directory to clean

up caches related to region or endpoint information. SeeCommand-line
interface scripts on page 715.
3. Check the Public Cloud Gateway log in the/var/log/pcg/pcg.log file for
problems.

Configuring subnets and security groups in a non-default VPC

region
You can configure subnets and security groups in a non-default VPC region.
If the non-default VPC support is enabled in one of your regions, you must tag at
least one subnet in each availability zone to be used as a default subnet in which
the virtual machines deployed in that region and availability zone are placed. Do
this in the Amazon VPC console of your account by adding a tag to the subnet
with key TenantUUId and value "*". The value "*" indicates that this subnet is used
for virtual machines for all projects.
It is possible to overwrite the "privateNetworkOnly definition on the region level
per subnet. If you want to do this, add a tag with the name privateNetworkOnly
and a value of either true or false to a subnet. The definition on the subnet has
precedence over the definition on the region.
If you want to place virtual machines of a distinct project in another subnet, you
can add the OpenStack tenant ID of your project as value for the TenantUUId tag.
You can only have one of these tags on a given subnet. Multiple subnets tagged
with the same OpenStack tenant ID are not allowed within a single availability
zone.
Additionally, you can tag one of the existing security groups with the key
TenantUUId and value "*" to be the default security group for all servers
provisioned in this region. If you want to place virtual machines of a distinct
project in another security group, you can add the OpenStack tenant ID of your
project as a value for the TenantUUId tag. You can only have one of those tags on a
given security group. Multiple security groups tagged with the same OpenStack
tenant ID are not allowed within a single VPC. As opposed to with subnets, you
do not have to tag a security group. In this case, the default security group of the
VPC is assigned.

Managing SoftLayer using the Public Cloud Gateway

The Public Cloud Gateway is not preconfigured for use with SoftLayer as part of
IBM Cloud Orchestrator. You must perform certain configuration tasks before using
the Public Cloud Gateway.

Before you begin

Familiarize yourself with the Public Cloud Gateway. See Public Cloud Gateway
overview on page 661.

Procedure
1. Check that prerequisites are met. See Prerequisites on page 675.
2. You can integrate SoftLayer using thePublic Cloud Gateway. See Integrating
SoftLayer using the Public Cloud Gateway on page 703.

702

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. You can configure the Public Cloud Gateway for SoftLayer. See Configuring
the Public Cloud Gateway for SoftLayer.
4. Create a supported image. See Creating a supported image on page 676.
5. Configure quotas. See Configuring quotas on page 690.

What to do next
For information about post-configuration steps, see Performing post-configuration
tasks on page 714.

Integrating SoftLayer using the Public Cloud Gateway

You can integrate SoftLayer using the Public Cloud Gateway.

Before you begin

For general information about SoftLayer, see http://www.softlayer.com/.

Procedure
1. Setup an account in SoftLayer and create one or more users IDs. Each ID has
its own unique password and API access key. The API access key is required in
configuring SoftLayer integration in the Public Cloud Gateway.
2. Create IBM Cloud Orchestrator-ready images.
3. Set up the following configuration files as described in Configuring the Public
Cloud Gateway on page 666. In particular, configure admin.json,
config.json, credentials.json, and flavors.json.
4. Start or restart the Public Cloud Gateway.

Configuring the Public Cloud Gateway for SoftLayer

You can configure the Public Cloud Gateway for SoftLayer.

Before you begin

There are some configuration steps required in the following files to add a region
and configure the credentials for a project:
v config.json.
v credentials.json.
Note: The examples shown in this section are only pieces of the config.json and
credentials.json files required for SoftLayer-specific configurations. Both files
contain additional sections that you must not modify or delete as part of the
SoftLayer configuration.
Configure regions in the config.json file:
Go to the /opt/ibm/pcg/etc directory and open the config.json file. The following
piece of code of the config.json file is relevant for the Softlayer region
configuration:
{
"vcenters":{
"softlayer":[
{
"name":"SL-Dallas05",
"dataCenter" : "Dallas 5",
"url":"https://api.softlayer.com/",
Chapter 8. Managing a hybrid cloud

703

"enabled":true
},
{
"name":"SL-Dallas06",
"dataCenter" : "Dallas 6",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-SanJose",
"dataCenter" : "San Jose 1",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-Amsterdam",
"dataCenter" : "Amsterdam 1",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-Seattle",
"dataCenter" : "Seattle",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-WashingtonDC",
"dataCenter" : "Washington 1",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-Singapore",
"dataCenter" : "Singapore 1",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-Dallas01",
"dataCenter" : "Dallas 1",
"url":"https://api.softlayer.com/",
"enabled":true
},
{
"name":"SL-HongKong",
"dataCenter":"Hong Kong 2",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-Houston",
"dataCenter":"Houston 2",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-Toronto",
"dataCenter":"Toronto 1",
"url":"https://api.softlayer.com/",
"enabled":false
},
{
"name":"SL-London",
"dataCenter":"London 2",
"url":"https://api.softlayer.com/",
"enabled":false

704

IBM Cloud Orchestrator 2.4.0.2: User's Guide

},
{
"name":"SL-Melbourne",
"dataCenter":"Melbourne 1",
"url":"https://api.softlayer.com/",
"enabled":false
}
]
}
}

The cloud region configuration is described in the vCenters section. Each region is
specified using three key-value pairs: name, url, and enabled. The parameters in
the config.json file are explained in the following table. Update the enabled
parameter to true if you want to specify that a particular region must be created in
Keystone.
Table 89. Parameters that are used in the config.json file
Parameter

Description

name

Name of the region as it appears in

keystone.

dataCenter

Name of the SoftLayer data center the

region is connected to.

url

SoftLayer: URL of SoftLayer API server. For

SoftLayer API server accessible via public IP
addresses, use https://api.softlayer.com/.
For accessing the SoftLayer API server on
the SoftLayer private network, use
https://api.service.softlayer.com/.

enabled

SoftLayer: Set to true if that datacenter is to

be made available to the users of IBM Cloud
Orchestrator. Set to false if that datacenter
is not available. The value of enabled is
either true or false: do not use quotation
marks.

Configure cloud credentials in the /opt/ibm/pcg/etc/credentials.json file.

Additional properties available for SoftLayer regions. Example for Singapore
datacenter:
{
"name":"SL-Singapore",
"dataCenter" : "Singapore 1",
"url":"https://api.softlayer.com/",
"enabled":false / true,
"ImageType" : "cloud-init" or "scp-init",
"privateNetworkOnly" : false / true,
"primaryVlanID" : "600516",
"backendVlanID": "600518"
}

Chapter 8. Managing a hybrid cloud

705

Table 90. Parameters that are used in the config.json file

Parameter

Description

ImageType

Defines on a region level what image

activation type must be returned for images.
The value is only used for images which are
not already tagged with a image type. See
Tagging images with the configuration
strategy on page 687.

privateNetworkOnly

If it is set to true, the virtual machine has a

single private NIC (backend). If it is set to
false, the virtual machine has a private
(backend) and a public (primary) NIC. The
default value is false.

primaryVlanID

VLAN ID that connects the virtual machine

to the internet (public VLAN). VLAN ID is
the SoftLayer resource ID that describes a
VLAN. If primaryVlanID is not specified, the
SoftLayer default is used. For the public
network, it is critical to configure the
firewall with the appropriate rules for the
user ID. The Public Cloud Gateway
performs the deployment with the
configured user ID (as specified in the
credentials.json file) so that the firewall
rules as defined for that user are applied for
the public network of the provisioned
virtual machine (for example, only HTTP
traffic, port 80 allowed).

backendVlanID

VLAN ID that connects the virtual machine

to the management network (private
VLAN). VLAN ID is the SoftLayer resource
ID that describes a VLAN. If backendVlanID
is not specified, the SoftLayer default is
used.

Note: To obtain the correct VLAN ID, perform the following steps:
1. Log on to SoftLayer portal at https://control.softlayer.com/.
2. Go to the VLANs page at https://control.softlayer.com/network/vlans.
3. Choose the VLAN that you want to use for provisioning and select it to open
the VLAN details.
4. Copy the VLAN ID from the browser URL. For example, if the URL is
https://control.softlayer.com/network/vlans/600516 then 600516 is the
correct ID. Do not confuse the VLAN ID with the VLAN number displayed on
the web page.
Configure cloud credentials in the /opt/ibm/pcg/etc/credentials.json file:
This file is used to specify SoftLayer credentials for each project. For more
information about defining projects, see Managing projects on page 275. The
SoftLayer credentials are mapped to specific projects in IBM Cloud Orchestrator.
These mappings are specified in the credentials.json configuration file.
Go to the /opt/ibm/pcg/etc directory and open the credentials.json file:

706

IBM Cloud Orchestrator 2.4.0.2: User's Guide

{
"cred":{
"softlayer":[
{
"tenantName":"admin",
"user_id":"xxx",
"api_access_key":"xxx"
},
{
"tenantName":"demo",
"user_id":"xxx",
"api_access_key":"xxx"
},
{
"tenantName":"tenant1",
"user_id":"xxx",
"api_access_key":"xxx"
},
{
"tenantName":"tenant2",
"user_id":"xxx",
"api_access_key":"xxx"
}
]
}
}

The parameters in the credentials.json are explained in the following table.

Update these parameters if you want to specify credentials to project mappings
and define what credentials must be used for the different projects specified.
Table 91. Parameters that are used in the credentials.json file
Parameter

Description

tenantName

Specifies the OpenStack project entity, also

known as tenant. The following options to
identify a project exist:
v OpenStack project ID.
v OpenStack project name.
v Wildcard * to match any project
Due to multi-domain support a project name
might not be unique, therefore a project ID
must be used. To get the project ID, use the
Administrative UI (Horizon) identity section.

user_id

This is the SoftLayer account user ID used

for the project.

api_access_key

This is the SoftLayer api access key. This

value must be encoded using the
encryptpassword.sh script that is available
in the ../opt/ibm/pcg directory.

Chapter 8. Managing a hybrid cloud

707

Table 91. Parameters that are used in the credentials.json file (continued)
Parameter

Description

region

This parameter specifies the region name as

defined in config.json. The region
parameter is optional. If this parameter is
set, the mapping is restricted to this specific
region. If it is not set, the mapping is valid
for all regions defined for the specific cloud
type in the config.json file.
Replace yyy in the example below with the
value of the name parameter as it is defined
in the config.json file. Example statement:
{
"tenantName":"*",
"region": "yyy",
"user_id":"xxx",
"api_access_key":"xxx"
}

Note: You must add a mapping for the project of the cloud administrator to the
credentials.json file. The default is admin. If this entry is missing, you cannot add
the availability zone to the domain using the Administration user interface.
{
"tenantName":"admin",
"region": "yyy",
"user_id":"xxx",
"api_access_key":"xxx"
},

where xxx is a valid set of credentials to access your SoftLayer account.

Activating configuration changes:

Procedure
1. Restart the Public Cloud Gateway by using the service pcg restart command.
For more information about starting the Public Cloud Gateway, see
Command-line interface scripts on page 715.
2. Execute the script in the /opt/ibm/pcg/refreshEndpoint.sh to clean up caches
related to region or endpoint information.
3. Check the Public Cloud Gateway log in /var/log/pcg/pcg.log for problems.

Managing non-IBM supplied OpenStack using the Public Cloud

Gateway
IBM Cloud Orchestrator is unable to manage non-IBM supplied OpenStack directly
due to the differences between IBM supplied OpenStack and non-IBM supplied
OpenStack. As a result of this, the Public Cloud Gateway can be used as an
interface between IBM Cloud Orchestrator and non-IBM supplied OpenStack.
The Public Cloud Gateway provides a compatibility layer that enables IBM Cloud
Orchestrator to manage Amazon EC2 images and instances by performing the
necessary translation to the Amazon EC2 API. This functionality can be used to
enable IBM Cloud Orchestrator to manage non-IBM supplied OpenStack services
by accessing them through their Amazon EC2 API.

708

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: Not all EC2 operations are supported by the OpenStack EC2
implementation. For example, the Resize Instance functionality is not supported
in Public Cloud Gateway by the OpenStack EC2 API.
Additional information on the capabilities of the OpenStack EC2 implementation is
available under API Feature Comparison at: https://wiki.openstack.org/wiki/
Main_Page.
The Public Cloud Gateway is not preconfigured for use with Amazon Elastic
Compute Cloud (Amazon EC2) as part of IBM Cloud Orchestrator. You must
complete certain configuration tasks before using the Public Cloud Gateway.
1. Familiarize yourself with the Public Cloud Gateway. See Public Cloud
Gateway overview on page 661.
2. Check that prerequisites are met. See Prerequisites on page 675.
3. Configure the Public Cloud Gateway to manage non-IBM supplied OpenStack.
For more information, see Configure the Public Cloud Gateway regions for
non-IBM supplied OpenStack and Configure non-IBM supplied OpenStack
EC2 credentials on page 711. You must already have one or more OpenStack
regions that are configured and functioning. For information about how to
install and configure a basic OpenStack instance, see http://docs.openstack.org.
4. Create a supported image. See Creating a supported image on page 676.
5. Configure quotas. See Configuring quotas on page 690.
For information about post-configuration steps, see Performing post-configuration
tasks on page 714.
The following configuration topics assume that you already have one or more
OpenStack regions that are configured and functioning. Instructions on how to
install and configure a basic OpenStack instance can be found at
http://docs.openstack.org.

Configure the Public Cloud Gateway regions for non-IBM

supplied OpenStack
The Public Cloud Gateway requires connection details for every non-IBM supplied
OpenStack region it manages.

Before you begin

The examples in this section are only pieces of the config.json required for the
non-IBM supplied OpenStack-specific configurations. The file contain additional
sections that you must not modify or delete as part of the non-IBM supplied
OpenStack configuration.

About this task

To obtain the connection details, log on to the host that is running the Keystone
service in each non-IBM supplied OpenStack region and complete the following
steps:

Procedure
1. Run the following command:
keystone service-list

Chapter 8. Managing a hybrid cloud

709

and look for the entry for Amazon EC2 and take note of the ID.
2. Run the following command:
keystone endpoint-list

and find the entry where the service_id matches the Amazon EC2 ID from the
previous step. Take a note of the publicurl also. It will be something similar to
http://<address>:8773/services/Cloud
Note: If you want the Public Cloud Gateway to manage more than one
non-IBM supplied OpenStack region, repeat these steps on the Keystone server
for each non-IBM supplied OpenStack region. This is required to obtain the
Amazon EC2 API interface address for each region.
3. The Public Cloud Gateway reads the connection details at startup from the
/opt/ibm/pcg/etc/config.json file on the Central Server 2 node. By default,
this file only contains the details of the Amazon EC2 regions. This file must be
updated to add the non-IBM supplied OpenStack regions to a data block
tagged nios inside the vcenters scope similar to this partial example:
"vcenters":{
"nios":[
{
"name":"nioRegion1",
"url":"http://192.0.2.12:8773/services/Cloud/",
"enabled":true
},
{
"name":"nioRegion2",
"url":"http://192.0.2.13:8773/services/Cloud/",
"enabled":true
}
]
},

Note: The url that is obtained from Keystone has a trailing / appended to it.
Note: The region name specified in the nios tag section must be a unique
name for that particular region.
Activating configuration changes
4. To activate configuration changes, complete the following steps:
a. Restart the Public Cloud Gateway by using the service pcg restart
command.
b. Execute the script refreshEndpoint.sh in the /opt/ibm/pcg directory to
clean up caches related to region or endpoint information.
c. Check for problems in the Public Cloud Gateway log: /var/log/pcg/
pcg.log.
For more information, see Command-line interface scripts on page 715.

What to do next
If the connection details contain a host name rather than an IP address, make sure
that the Central Server 2 node can resolve the host names and add entries to the
/etc/hosts file if required. Alternatively, use the IP address rather than the host
name in the config.json file.

710

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Configure non-IBM supplied OpenStack EC2 credentials

The credentials that are used on the Amazon EC2 API are different from the
credentials that are used by the OpenStack API. As a result, you must generate
these special credentials and configure the Public Cloud Gateway to use them
when accessing the non-IBM supplied OpenStack services.
The credentials that the Public Cloud Gateway uses on the Amazon EC2 API
interface are checked by the Keystone service that is running in the non-IBM
supplied OpenStack region. As a result, you must use the non-IBM supplied
OpenStack Keystone service to generate the Amazon EC2 API credentials.
1. The command that is used to create the Amazon EC2 credentials requires the
32-digit IDs of the user and tenant that are copied during the Amazon EC2 API
calls. Log on to the non-IBM supplied OpenStack Keystone host in each
non-IBM supplied OpenStack region and obtain these IDs using the commands:
keystone user-list
keystone tenant-list

Note: The user and tenant that are chosen must have sufficient access to
perform the necessary actions on Nova and Glance. Use the admin user and
admin tenant unless you have suitable alternatives that are configured on the
non-IBM supplied OpenStack Keystone.
2. Create the Amazon EC2 credentials using the command:
keystone ec2-credentials-create --tenant-id <tenant ID> --user-id <user ID>

If successful, the command returns two new 32-bit keys that are called Access
and Secret.
Note: Amazon EC2 credentials that are created on non-IBM supplied
OpenStack Keystone apply to both tenant and user when using these
credentials. For example, when deploying a virtual machine, the virtual
machine is created using the tenant and the user specified in the previous
command.
3. The following example shows the previous steps where Amazon EC2
credentials are created on the non-IBM supplied OpenStack using the admin
tenant and the admin user: :
root@nio3:/etc/glance# keystone user-list
+----------------------------------+---------+---------+--------------------+
|
id
|
name | enabled |
email
|
+----------------------------------+---------+---------+--------------------+
| 475e0cb45d1049cbb5bddf1eb508b391 | admin |
True | [email protected] |
| 901653358e49460297fbba3dfb0848cf | cinder |
True | [email protected] |
| 79fabd02dc1f43aabc03f77d97a840ee |
demo |
True | [email protected] |
| 00cb0e8b6d734e7499fca57d077b0fc1 | glance |
True | [email protected] |
| 10f54c9b123147c488ae3c942143acc8 |
nova |
True | [email protected] |
| 940f130d79cc46b9ae38ae6bda929767 | quantum |
True | [email protected] |
+----------------------------------+---------+---------+--------------------+
root@nio3:/etc/glance# keystone tenant-list
+----------------------------------+---------+---------+
|
id
|
name | enabled |
+----------------------------------+---------+---------+
| 40a39220bf5747edaac54216b5e8eb60 | admin |
True |
| 7cdafa91633a43d19e773bdbe0b28b76 |
demo |
True |
| 0420552b5721451a9d42b5e96ba79444 | service |
True |
+----------------------------------+---------+---------+
root@nio3:/etc/glance# keystone ec2-credentials-create
--tenant-id 40a39220bf5747edaac54216b5e8eb60
--user-id 475e0cb45d1049cbb5bddf1eb508b391
Chapter 8. Managing a hybrid cloud

711

+-----------+----------------------------------+
| Property |
Value
|
+-----------+----------------------------------+
|
access | 7e3d858e92324564a31e5d9b50fa62f0 |
|
secret | 98d7e15c0ae649b6a90bcbd8f9dbb725 |
| tenant_id | 40a39220bf5747edaac54216b5e8eb60 |
| user_id | 475e0cb45d1049cbb5bddf1eb508b391 |
+-----------+----------------------------------+
root@nio3:/etc/glance#

Note: If the Keystone ec2-credentials-create command is run a second time,

even if the same user ID and tenant ID are used, the result are different and the
previous access and secret key becomes invalid. Also, ensure that the
commands are run on each separate non-IBM supplied OpenStack region that is
controlled by the Public Cloud Gateway. This is required as different Keystone
instances generate different IDs for the same user name or tenant name.
4. Before the secret key can be used, it must be base-64 encoded using the
encryptpassword.sh script:
v Edit /opt/ibm/pcg/etc/credentials.json on the Central Server 2 machine.
v In the nios section, insert a new block of data with the correct region name,
tenant name, access key, and encoded secret key.
Note: Take care to insert the appropriate comma if a new block is being
appended to an existing section.
Note: Credentials must be defined for all IBM Cloud Orchestrator tenants.
v Save the file.
Note: The examples in this section are only pieces of the credentials.json
required for the non-IBM supplied OpenStack specific configurations. The file
contains additional sections that you must not modify or delete as part of the
non-IBM supplied OpenStack configuration.
The following example of credentials.json shows the formatting:
{
"cred":{
"nios":[
{
"tenantName":"admin",
"access_key_ID":"xxx",
"secret_access_key":"xxx",
"region":"nioRegion1"
}
]
}
}

The parameters in the credentials.json are described in the following table.

Update these parameters if you want to specify credentials to project mappings
and define what credentials must be used for the different projects specified.

712

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 92.
Parameter

Description

tenantName

TenantName specifies the OpenStack project entity,

also known as tenant. The following options to
identify a project exist:
v OpenStack project ID
v OpenStack project name
v Wildcard * to match any project.
Note: Due to multi-domain support, a project name
might not be unique, therefore a project ID must be
used. To get the project ID, use the Administrative UI
(Horizon) identity section.

access_key_ID

This is the non-IBM supplied OpenStack access key

for the project.

secret_access_key

This is the non-IBM supplied OpenStack

secret_access_key used for the project. This value
must be encoded using the encryptpassword.sh
script that is available in the ../opt/ibm/pcg
directory.

region

This is the name of the region as defined in the

config.json file for the non-IBM supplied
OpenStack. This parameter is required.

Note: You must add a mapping for the project of the cloud administrator to the
credentials.json. The default is "admin". If this entry is missing, you cannot add
the availability zone to the domain via the IBM Cloud Orchestrator Administration
UI.
{
"tenantName":"admin",
"region":"yyy"
"access_key_ID":"xxx",
"secret_access_key":"xxx"
},

where xxx is a valid set of credentials to access your Amazon EC2 account.

Activating configuration changes

Complete the following steps:
1. Restart the Public Cloud Gateway by using the service pcg restart command.
2. Execute the script refreshEndpoint.sh in the /opt/ibm/pcg directory to clean
up caches related to region or endpoint information.
3. Check for problems in the Public Cloud Gateway log: /var/log/pcg/pcg.log.
For more information, see Command-line interface scripts on page 715.

Chapter 8. Managing a hybrid cloud

713

Performing post-configuration tasks

You must complete post-configuration tasks after you configure the Public Cloud
Gateway.

About this task

You can deploy a single virtual machine or a virtual pattern. The
post-configuration steps are different for each scenario.

Procedure
1. For deployment using a single virtual machine, complete the following steps:
a. Add the newly-defined Public Cloud Gateway managed region or
availability zone to:
Domain
See Assigning a zone to a domain on page 262.
Project
See Assigning a zone to a project on page 267.
b. Register a new SSH key for deployment. See Registering a key pair on
page 322.
c. If you want to use additional disks during deployment, you must create
volumes for the project. You can create volumes using the OpenStack
Cinder Storage Volumes toolkit.
d. Add cloud-init to Linux operating system images, as described in Adding
cloud-init to Linux images on page 336.
e. Deploy the virtual machine as described in Deploying a virtual machine
on page 314.
2. For deployment using virtual patterns, complete the following steps:
a. Update the NTP servers list to include a valid NTP server for the new
Public Cloud Gateway managed region. For more information about the
NTP servers list, see Setting NTP servers on page 83.
The default NTP configuration is only valid for new servers that can reach
the Deployment Server node via DNS. A publicly accessible NTP server is
required for servers in public clouds. Examples are:
v 0.amazon.pool.ntp.org
v 1.amazon.pool.ntp.org
v 2.amazon.pool.ntp.org
v 3.amazon.pool.ntp.org
For SoftLayer, you can use servertime.service.softlayer.com as an NTP
server.
b. Before you create a Linux image, ensure that the software requirements are
met, as described in Software prerequisites for Linux images (KVM or
VMware hypervisors) on page 337.
c. Deploy the virtual pattern as described in Chapter 7, Managing and
deploying virtual patterns, on page 353.

Results
You can now deploy a virtual machine or virtual pattern by using the Public
Cloud Gateway.

714

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Reference
This section provides reference information for the Public Cloud Gateway.

Key pairs
Key pairs are needed to access the virtual machines that you deployed. When you
deploy a virtual machine, these keys are injected into the instance to allow
password-less SSH access to the instance.
The default key pair that is created from the Self-service user interface in Amazon
EC2 regions is appended with the user ID of the user that created the key pair. For
example, if the user creating the key pair in the Self-service user interface is admin,
the name of the key pair that is created in Amazon EC2 is default_admin. For
information about managing key pairs, see Managing key pairs on page 322.

Command-line interface scripts

Command Line Interface (CLI) scripts are available in the /opt/ibm/pcg directory.
These scripts are used for manual tasks, for example, starting the Public Cloud
Gateway, encrypting a password, changing port numbers, and so on.
encryptPassword.sh plaintext_password
Writes an encrypted password to stdout. This script is used for encrypting
passwords and access keys that are used in the admin.json and
credentials.json files, which are located in the /opt/ibm/pcg/etc
directory. The command must be run in the directory where the
encryptPassword.sh script is located.
service pcg start
Starts the Public Cloud Gateway server with the default settings.
Note: The default port number for the Public Cloud Gateway server is
9797. To change this value, you must edit the startServer.sh script and
change the value of -DHybrid.Port to the new port number.
service pcg stop
Stops the Public Cloud Gateway server.
service pcg restart
Restarts the Public Cloud Gateway server.
refreshEndpoint.sh admin_userid admin_password bpm_hostname:bpm_port
Refreshes the IBM Cloud Orchestrator endpoint cache, where
v admin_userid is the user name of the Cloud Administrator user.
v admin_password is the password of the specified Cloud Administrator
user.
v bpm_hostname is the host name of the Business Process Manager server.
Business Process Manager usually runs on the same host as the Public
Cloud Gateway.
v bpm_port is the port of the Business Process Manager server. The default
port is 9443.
The refreshEndpoint.sh script must be run if region information is
changed within the Public Cloud Gateway config.json file. If the
command was successful, the command output includes the following line:
HTTP/1.1 204 No Content

Chapter 8. Managing a hybrid cloud

715

To see any new Regions or Availability Zones in the IBM Cloud

Orchestrator user interface lists, users must log out of the user interface
and log back in again.

Password authentication on Amazon EC2 images

You can allow password authentication on Amazon EC2 images.
Usually, Amazon Linux images have password and root login disabled by default.
Amazon AWS EC2 recommends to use SSH keys to access the images. The images
are usually also sudo enabled.
You can enable password and root login using the following procedure:
1. Update the cloud-init configuration file on page 680 to allow root access and
password login.
2. Update the authorized_keys file on page 680.
3. Update the sshd_config file on page 680 to enable password authentication
and root login.
Note: Future Amazon updates to the images might require changes to the
procedure.

Update the cloud-init configuration file

Make sure that the following lines are in the /etc/cloud/cloud.cfg file:
disable_root: false
ssh_pwauth:
true

These properties enable root login and password authentication in cloud-init. They
are required to set the password via user-data.

Update the authorized_keys file

In the authorized_keys file, remove the command prefix and leave only the
ssh-rsa statement. For example, change the following default content:
no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="echo Please login
as the user \"ec2-user\" rather than the user \"root\".;echo;sleep 10"
ssh-rsa <content of sshkey>

to the following content:

ssh-rsa <content of sshkey>

Update the sshd_config file

Log on to the Amazon EC2 image by using SSH and complete the following steps:
1. Edit the /etc/ssh/sshd_config file.
2. Update the following lines:
PasswordAuthentication yes
PermitRootLogin yes

3. Save the file.

4. Run the following command:
sudo service sshd restart

716

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 9. Integrating
Learn how to integrate IBM Cloud Orchestrator with the following IBM products.

Integrating with IBM Tivoli Monitoring

To integrate IBM Cloud Orchestrator with IBM Tivoli Monitoring, you must
prepare a base operating system, set up the required databases, install the Tivoli
Monitoring components, and deploy the Monitoring Agents to monitor the IBM
Cloud Orchestrator environment.

Preparing a base operating system

IBM Tivoli Monitoring 6.3.0.2 supports several operating systems, but the IBM
Cloud Orchestrator solution is based on Red Hat Enterprise Linux (RHEL), which
makes it an optimal system for setting up Tivoli Monitoring.

Before you begin

For a list of supported operating systems, see Supported operating systems.
For more information about hardware and software requirements for IBM Tivoli
Monitoring, see Hardware and software requirements.

Procedure
1. You must install several rpm packages that are required by IBM Global Security
Toolkit (GSKit). GSKit is deployed automatically with the Tivoli Monitoring
installation and requires the following operating system patches:
v ksh-20091224-1.el6.x86_64.rpm
v glibc-2.12-1.7.el6.i686.rpm
v libgcc-4.4.4-13.el6.i686.rpm
v nss-softokn-freebl-3.12.7-1.1.el6.i686.rpm
2. Install the libraries that are required by the OS Monitoring Agent:
v libstdc++
v libgcc
v compat-libstdc++
Restriction: On a 64-bit system, you must have 32-bit and 64-bit versions of
those libraries.

Copyright IBM Corp. 2013, 2015

717

Database setup
IBM Tivoli Monitoring requires two databases, the Tivoli Enterprise Portal Server
database and the Tivoli Data Warehouse database.
v The Tivoli Enterprise Portal Server database, or portal server database, stores
user data and information that is required for graphical presentation on the user
interface. The portal server database is created automatically during
configuration of the portal server. It is always on the same computer as the
portal server.
v The Tivoli Data Warehouse database, also called the warehouse database or data
warehouse, stores historical data for presentation in historical data views. In a
single-computer installation, the warehouse database is created on the same
relational database management server that is used for the portal server
database. In larger environments, it is best to create the warehouse database on a
different computer from the portal server.
You can create a TEPS database on an embedded Derby database that is delivered
with the Tivoli Monitoring installer. Warehouse database can be set on a DB2 or
Oracle server. Thus, the best solution is to install a DB2 server on a Tivoli
Monitoring server and use it for TEPS and Warehouse databases.
For more information about installing DB2, see the DB2 documentation.

Installing IBM Tivoli Monitoring

The installation of IBM Tivoli Monitoring requires several mandatory components.
You can also install extra ones if you are planning to set up a dashboard
environment or use products that support integration using OSLC.

About this task

For more information about Tivoli Monitoring and its components, see
Components of the monitoring architecture.
For more information about installing and configuring Tivoli Monitoring, see
High-level installation steps.

Procedure
1. You must install the following components of Tivoli Monitoring:
v Hub Tivoli Enterprise Monitoring Server
v Tivoli Enterprise Portal Server
v Tivoli Enterprise Portal desktop client
v The Warehouse Proxy Agent
v The Summarization and Pruning Agent
2. If you plan to set up a dashboard environment, you can install extra
components. For base installation, these features are not required and can be
skipped or installed later:
v Dashboard Application Services Hub (a Jazz for Service Management
component)
v IBM Infrastructure Management Dashboards for Servers
v Tivoli Authorization Policy Server
v tivcmd Command Line Interface for Authorization Policy

718

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Dashboard and JazzSM are new components of Tivoli Monitoring 6.3.

Dashboard does not completely replace Tivoli Portal Client but is used to
improve data presentation. TEPS is used for configuration issues.
3. If you plan to use the Performance Monitoring service provider to integrate
with the Jazz for Service Management Registry Services component and other
products that support integration using OSLC, install the following component.
For base installation, this feature is not required and can be skipped or installed
later:
v Tivoli Enterprise Monitoring Automation Server

Packages used for installation

You need several packages to install IBM Tivoli Monitoring 6.3.0.2. All of its
components can also be installed in silent mode.
The following packages are required to install IBM Tivoli Monitoring 6.3.0.2:
v CIQ3JEN - IBM Tivoli Monitoring V6.3.0.2 Base, Linux (64-bit Env.), English
v CIQ3PML - IBM Tivoli Monitoring V6.3.0.2 Dashboards for Servers and
Authorization Policy Components Assembly Multiplatform, Multilingual
v CIQ3MML - IBM Tivoli Monitoring V6.3.0.2 Language Support Multiplatform
Multilingual
All IBM Tivoli Monitoring components can be installed and configured in silent
mode. First, you must install all products with one silent_install file and then
configure each one of them with silent_config response files. For more
information about modifying the files, see the following examples.
v IBM Tivoli Monitoring: modify the silent_install.txt file with the following
information:
INSTALL_PRODUCT=ms
INSTALL_PRODUCT=cq
INSTALL_PRODUCT=hd
INSTALL_PRODUCT=sy
INSTALL_PRODUCT_TMS=all
INSTALL_PRODUCT_TPS=all
INSTALL_PRODUCT_TPW=all
INSTALL_ENCRYPTION_KEY=IBMTivoliMonitoringEncryptionKey
SEED_TEMS_SUPPORTS=true
MS_CMS_NAME=TEMS
DEFAULT_DISTRIBUTION_LIST=NEW

v Tivoli Enterprise Monitoring Server: modify the ms_silent_config.txt file with

the following information:
HOSTNAME=itmsrv1
NETWORKPROTOCOL=ip.pipe
SECURITY=YES

v Tivoli Enterprise Portal Server: modify the cq_silent_config.txt file with the
following information:
CMSCONNECT=YES
HOSTNAME=itmsrv1
NETWORKPROTOCOL=ip.pipe
DB2INSTANCE=db2inst1
DB2ID=itmuser
DB2PW=passw0rd
WAREHOUSEID=itmuser
WAREHOUSEDB=WAREHOUS
WAREHOUSEPW=passw0rd
ADMINISTRATORID=db2inst1
ADMINISTRATORPW=passw0rd

Chapter 9. Integrating

719

v Summarization and Pruning Agent: modify the sy_silent_config.txt file with

the following information:
CMSCONNECT=YES
HOSTNAME=itmsrv1
NETWORKPROTOCOL=ip.pipe
KSY_WAREHOUSE_TYPE=DB2
KSY_WAREHOUSE_JARS=/opt/ibm/db2/v10.1/java/db2jcc.jar,/opt/ibm/db2/v10.1/java/db2jcc_license_cu.jar
KSY_DB2_JDBCURL=jdbc:db2://db2srv1:50001/WAREHOUS
KSY_DB2_JDBCDRIVER=com.ibm.db2.jcc.DB2Driver
KSY_WAREHOUSE_USER=itmuser
KSY_DB_COMPRESSION=N
KSY_TIMEZONE_IND=AGENT
KSY_START_OF_WEEK_DAY=0
KSY_SHIFTS_ENABLED=N
KSY_SHIFT1_HOURS=0,1,2,3,4,5,6,7,8,18,19,20,21,22,23
KSY_SHIFT2_HOURS=9,10,11,12,13,14,15,16,17
KSY_VACATIONS_ENABLED=N
KSY_WEEKENDS_AS_VACATIONS=N
KSY_VACATION_DAYS=
SY_MAX_ROWS_PER_TRANSACTION=1000
KSY_FIXED_SCHEDULE=Y
KSY_EVERY_N_DAYS=1
KSY_HOUR_TO_RUN=2
KSY_HOUR_AM_PM=AM
KSY_MINUTE_TO_RUN=0
KSY_EVERY_N_MINS=60
KSY_BATCH_MODE=0
KSY_CNP_SERVER_HOST=localhost
KSY_CNP_SERVER_PORT=1920
KSY_HOUR_AGE_UNITS=1
KSY_DAY_AGE_UNITS=0
KSY_MAX_WORKER_THREADS=2
KSY_CACHE_MINS=10

v Warehouse Agent: modify the hd_silent_config.txt file with the following

information:
CMSCONNECT=YES
HOSTNAME=itmsrv1
NETWORKPROTOCOL=ip.pipe
KHD_DBMS=DB2
KHD_WAREHOUSE_JARS=/opt/ibm/db2/v10.1/java/db2jcc.jar,/opt/ibm/db2/v10.1/java/db2jcc_license_cu.jar,
/opt/ibm/db2/v10.1/java/db2jcc4.jar,/opt/ibm/db2/v10.1/java/db2policy.jar
KHD_DB2_JDBCURL=jdbc:db2://nc045061:50001/WAREHOUS
KHD_DB2_JDBCDRIVER=com.ibm.db2.jcc.DB2Driver
KHD_WAREHOUSE_USER=itmuser
KHD_WAREHOUSE_PASSWORD=passw0rd
KHD_BATCH_USE=true
KHD_DB_COMPRESSION=false
KHD_SERVER_Z_COMPRESSION_ENABLE=false
KHD_SERVER_DIST_COMPRESSION_ENABLE=true

Creating a warehouse database

IBM Tivoli Monitoring supports a remote data warehouse through aliases in a local
DB2 server.

About this task

For more information about creating a warehouse database, see Creating the Tivoli
Data Warehouse database.

Procedure
1. Create a warehouse database on a remote server.
2. Create a DB2 user on a remote server. Grant the user administrative rights to
the database.

720

IBM Cloud Orchestrator 2.4.0.2: User's Guide

3. On local DB2 on which IBM Tivoli Monitoring is installed, catalog a remote

data warehouse.

Monitoring Agent for Linux

To monitor the entire IBM Cloud Orchestrator environment, install Monitoring
Agent on each Linux computer and configure it with the host name of your Tivoli
Enterprise Monitoring Server.
For more information about installing the operating system agents, see Installing
monitoring agents.
The operating system agents are delivered with the following package:
v CIQ3QML - IBM Tivoli Monitoring V6.3.0.2 Agents, Multiplatform, Multilingual
If you want to use silent mode to install and configure the agents, you can use the
following files:
v silent_install.txt. You can use this file without any changes.
v lz_silent_config.txt. Modify the file with the following information:
CMSCONNECT=YES
HOSTNAME=itmsrv1
NETWORKPROTOCOL=ip.pipe

If you want the agents to report to your main Tivoli Enterprise Monitoring Server,
configure each one of them with such a configuration file.

Monitoring Agent for Kernel-based virtual machines

The KVM agent is used to monitor the Region Server and it must be installed with
other ITM 6.3.0.2 components. The agent requires the libvirt library that is used
to connect with the monitored KVM hypervisor.
For more information about installing and configuring the agent, see Linux
Kernel-based virtual machines agent.
To properly configure the agent, you must provide parameters that describe the
hypervisor.
You must add the RSA public keys of host on which the KVM agent is deployed to
the hypervisor to enable communication through the SSH protocol. The protocol is
configured and enabled for the Kernel services that are created by the Region
Server, but you must enable it between the Region Server and the computer on
which IBM Tivoli Monitoring is installed.
For more information about configuring the SSH protocol, see SSH protocol.
The KVM agent requires the following packages:
v CIQ4HEN - IBM Tivoli Monitoring for Virtual Environments V7.2.0.2 VMware
VI, KVM, NetApp Storage and NMA Agents and Support Files, Windows and
Linux, English, Multiplatform
v CIQ4JML - IBM Tivoli Monitoring for Virtual Environments V7.2.0.2 Agent
Language Pack, Multiplatform, Multilingual
If you want to use silent mode for installing and configuring the operating system
agents, you can use the following files:
v Modify the silent_install.txt file with the following information:
Chapter 9. Integrating

721

INSTALL_PRODUCT=v1
INSTALL_PRODUCT_TMS=all
INSTALL_PRODUCT_TPS=all
INSTALL_PRODUCT_TPW=all
INSTALL_ENCRYPTION_KEY=IBMTivoliMonitoringEncryptionKey
SEED_TEMS_SUPPORTS=true
MS_CMS_NAME=TEMS
DEFAULT_DISTRIBUTION_LIST=NEW

v Modify the v1_silent_config.txt with the following information:

CMSCONNECT=YES
HOSTNAME=itmsrv1
NETWORKPROTOCOL=ip.pipe
INSTANCE=RegionServer
DATA_PROVIDER.KV1_LOG_FILE_MAX_COUNT=10
DATA_PROVIDER.KV1_LOG_FILE_MAX_SIZE=5190
DATA_PROVIDER.KV1_LOG_LEVEL=INFO
HOST_ADDRESS.RegionServer=<host name of the region server visible by itmsrv1>
USERNAME.RegionServer=root
PROTOCOL.RegionServer=ssh
PORT.RegionServer=22
CONNECTION_MODE.RegionServer=system

OpenStack hypervisors
With the default configuration, you can monitor the Region Server as a KVM
hypervisor. To do so, you can use Monitoring Agent for Kernel-based virtual
machines from Tivoli Monitoring for Virtual Environments.
OpenStack can use different hypervisors, like KVM or VMware. To monitor
different KVM hypervisors, you can use the installed agent and simply add a new
instance in the agent configuration.
To monitor a VMware hypervisor, you must install and configure Monitoring
Agent for VMware, which is also included in Tivoli Monitoring for Virtual
Environments. Then, you can add an instance of configuration every time a new
hypervisor is added to OpenStack.
For more information about VMware Agent, see VMware VI User's Guide.

Integrating with IBM Endpoint Manager

To integrate IBM Cloud Orchestrator with IBM Endpoint Manager follow these
topics.

About this task

The purpose of this document is to demonstrate how IBM Endpoint Manager can
be integrated with IBM Cloud Orchestrator. The first topic describes a tool which
can be used to deploy Endpoint Manager agents to existing computers. The
following topic describes how a script package pattern component can be created
to automatically install the IBM Endpoint Manager agent when deploying a virtual
system. Installing the agent as a script package eliminates the need to manually
install agents on newly deployed virtual systems. The procedure described in that
topic also demonstrates policy-based patch management of virtual systems
provisioned through IBM Cloud Orchestrator.
Note: Install and set up IBM DB2 V10.5 to support IBM Cloud Orchestrator. If you
subsequently install IBM Endpoint Manager, do not install the IBM DB2
Workgroup Server Edition that is included with IBM Endpoint Manager. Continue

722

IBM Cloud Orchestrator 2.4.0.2: User's Guide

to use the IBM DB2 Enterprise Server Edition V10.5, because IBM Endpoint
Manager will be used in the context of IBM Cloud Orchestrator.

Installing Endpoint Manager agent to existing computers

Using the IBM Endpoint Manager agent deployment wizard, you can deploy the
IBM Endpoint Manager agent to computers in your network.
Use the wizard to enter the details of the computers to which you want to deploy
the agent and then select the agent version and the client configuration. The
wizard provides feedback on each step of the process and displays the results of
the deployment for each individual computer.
Download the Beta version of the Endpoint Manager agent deployment wizard at:
http://software.bigfix.com/download/bes/util/AgentDeployment/
TEMAgentDeployment-1.0.446-win.zip.

Installing Endpoint Manager agents during virtual machine

deployment
Use a custom script package to deploy Endpoint Manager agents during virtual
machine deployment.
To integrate Endpoint Manager with the IBM Cloud Orchestrator, create a custom
script package. When the pattern associated with the script package is deployed an
Endpoint Manager agent, it is installed on the target system. The agent allows
registration and communication between the target system and the Endpoint
Manager server.
The behavior of parts in IBM Cloud Orchestrator topologies can be customized by
adding script packages to pattern topologies. Custom script packages can be
created and then added to the required part within the pattern containing that
part.
Policy-based patch management of virtual systems can be achieved by configuring
groups, within Endpoint Manager, based on the value of a specific environment
variable set on the managed virtual machine. The value of this specific
environment variable can be defined during the deployment of the virtual
machine, in other words, during pattern deployment in IBM Cloud Orchestrator.

Endpoint Manager install agent script package

A script package is a compressed file that contains the executable file and all
associated files for the script package. The compressed file includes the executable
file (script.sh on Linux, or script.bat or script.cmd on Windows) plus the .json
file (cbscript.json) needed to run the script on the deployed virtual machine.
The Endpoint Manager install agent script package contains the following files:
v Endpoint Manager Server Masthead file (actionsite.afxm).
v Endpoint Manager agent installer (*.rpm / setup.exe).
v Script package executable (script.sh or script.bat).
v JSON configuration file (cbscript.json).
where:
Endpoint Manager Server Masthead file
The masthead file is generated during installation of the target Endpoint
Chapter 9. Integrating

723

Manager server. The masthead file contains configuration, license, and

security information unique to each installation. The file has the extension
.afxm and can be retrieved in the following ways:
v In the database of the target IBM Tivoli Endpoint Manager server. Use
the Admin Tool to export the masthead file.
v On the target IBM Endpoint Manager server named Actionsite.afxm,
and found in one of the following site version folders located at:
C:\Program Files\BigFix\Enterpriese\BES\Server\sitearchive\
actionsite\archiveDir\actionsite_<XXX>
Note: If the masthead is not named actionsite.afxm, rename it to
actionsite.afxm.
Endpoint Manager Agent Installer
This file is the installer for the Endpoint Manager agent and is dependent
on the Endpoint Manager server version and on the operating system
version the agent is being deployed to. It can be retrieved in the following
ways:
Windows:
The Endpoint Manager agent installer can be found on the
Endpoint Manager server in the installation folder: C:\Program
Files (x86)\BigFix Enterprise\BES Console\BESClientDeploy\
BigFixInstallSource\ClientInstaller. The file is named
setup.exe.
Linux: The Endpoint Manager agent installer for non-windows operating
systems can be found at http://support.bigfix.com/install/
besclients-nonwindows.html. The file is named BESAgent<Endpoint
Manager version>-<os version>.rpm. For example, on Red Hat Linux:
BESAgent-8.2.1175.0-sle11.x86_64.rpm.
Script package executable
This file is created manually. It is executed when the script package is run
on the newly deployed system. It configures and runs the Endpoint
Management agent installer file:
Windows:
script.bat
Linux: script.sh
JSON configuration file
This file is created manually. It is used to populate all the information
needed to configure a script package when it is added to the catalog. The
file must be called cbscript.json.

Policy-based Patch Management

Policy-based patch management can be achieved using groups in Endpoint
Manager. To configure groups of virtual systems within Endpoint Manager, create
a Computer Group which groups computers based on the value of the
_BESCLIENT_GROUP_NAME environment variable.
For example, in an Automatic Group, set the property Relevance Expression to
true and add the following constraint:
exists setting "_BESClient_GROUP_NAME" of client AND
value of setting "_BESClient_GROUP_NAME" of client = "<MY_VALUE>".

724

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This groups any computers which have the _BESCLIENT_GROUP NAME set to
<MY_VALUE>. During the deployment of the virtual system, _BESCLIENT_GROUP
NAME should be set to MY_VALUE to be included in this group.
To assign a virtual machine to a specific group during deployment, the Endpoint
Manager install agent script package contains the following environment
variable: _BESCLIENT_GROUP_NAME. This environment variable corresponds to the
_BESCLIENT_GROUP_NAME client setting configured within the Endpoint Manager
server and can be used to group virtual systems within the Endpoint Manager
server.
The _BESCLIENT_GROUP_NAME environment variable is by default set to none and
ignored but can be modified when deploying a virtual system.

Example script package to install an Endpoint Manager agent on

Red Hat Linux
This script package installs an Endpoint Manager agent on a Red Hat Linux
system and configures an environment variable which is used by the Endpoint
Manager server to group virtual machines:
v Retrieve the Endpoint Manager Server Masthead from the Endpoint Manager
Server machine. If the masthead is not named actionsite.afxm, rename it to
actionsite.afxm.
v Retrieve the appropriate Red Hat Linux agent installer (.rpm) from
http://support.bigfix.com/install/besclients-nonwindows.html, for example,
BESAgent-8.5.6666.0-rhe5.x86_64.rpm.
v Create the install.sh script as follows, replacing the <SERVER IP> and
<SERVER HOSTNAME> placeholders with the correct IP and host name values
corresponding to the Endpoint Management server machine. If the Endpoint
Manager server port is not the default value of 52311, replace this value with the
correct port number:
# Source the env file
if [ -f "/etc/virtualimage.properties"]; then.
/etc/virtualimage.properties
fi
# install the IEM client package
rpm -ivf /tmp/IEMClient/BESAgent*.rpm
# copy the actionsite masthead
cp /tmp/IEMClient/actionsite.afxm /etc/opt/BESClient
# resolve IEM server shortname to ip address
echo "<SERVER IP><SERVER HOSTNAME">>/etc/hosts
# Add the IEM Server port 52311 to iptablesif
[ -f "/etc/init.d/SuSEfirewall2_init"]; then
# SUSE/SLES host
/etc/init.d/SuSEfirewall2_init status /dev/null 2>&1
if [ $? -eq 0 ]; then
/etc/init.d/SuSEfirewall2_setup stop
iptables -A INPUT -p tcp --dport 52311 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 52311 -j ACCEPT
/etc/init.d/SuSEfirewall2_setup reload
fi
else
/etc/init.d/iptables status >/dev/null 2&1
if [ $? -eq 0 ]; then
# save the iptables and then stop it
/etc/init.d/iptables save
Chapter 9. Integrating

725

/etc/init.d/iptables stop
iptables -A INPUT -p tcp --dport 52311 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 52311 -j ACCEPT
/etc/init.d/iptables save
/etc/init.d/iptables start
fi
fi
# If the _BESCLIENT_GROUP_NAME is set (default is none i.e. ignore)
if [ ! "${_BESCLIENT_GROUP_NAME}"== "none"]; then
echo "Group policy to be set to: ${_BESCLIENT_GROUP_NAME}"
echo "[Software\BigFix\EnterpriseClient\Settings\Client\
_BESCLIENT_GROUP_NAME]">>/var/opt/BESClient/besclient.config
echo "value = ${_BESCLIENT_GROUP_NAME}">>/var/opt/BESClient/besclient.config
fi
# start the IEM client
/etc/init.d/besclient start

v Create the cbscript.json file. Make sure that the name specified in the file
matches the script package zip name, for example: IEM_8.5.6666.0rhe5.x86_64.zip:
[
{
"name": "IEM_8.5.6666.0-rhe5.x86_64",
"version": "1.0.0",
"description": "This script package installs the IEM Agent on RHEL 5 64-bit ",
"command": "/bin/sh /tmp/IEMClient/install.sh",
"log": "/tmp/IEMClient",
"location": "/tmp/IEMClient",
"timeout": "0",
"commandargs":"",
"keys":
[
{
"scriptkey": "_BESCLIENT_GROUP_NAME",
"scriptvalue": "",
"scriptdefaultvalue": "none"
}
]
}
]

v The script package name must match the name specified in the cbscript.json
file. Create the script package by zipping together the following files (for
example, IEM_8.5.6666.0-rhe5.x86_64.zip):
actionsite.afxm - the Endpoint Manager Server Masthead.

v
v
v

BESAgent-8.5.6666.0-rhe5.x86_64.rpm - the agent installer for Red Hat Linux.

install.sh.
cbscript.json.
Import the script package zip file into IBM Cloud Orchestrator and keep the
default setting Executes at virtual system creation.
Create a pattern containing a Red Hat Linux part and add the script package to
this part.
Optional. Configure a Computer Group, in the Endpoint Manager Server
console, to match the proposed _BESCLIENT_GROUP_NAME environment variable
value set when the virtual system is deployed.
Deploy the pattern. Optional: Specify the value for the _BESCLIENT_GROUP_NAME
environment variable to match the Computer Group configured in the Endpoint
Manager console. By default this value is set to none and is ignored.

v The script package runs when the virtual system is deployed. To verify that the
agent is installed correctly review the log files.

726

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v After the agent has registered with the Endpoint Manager server, the computer
system information is displayed in the Endpoint Manager console.
v If a group has been configured and set, the computer also displays under the
specific group heading in the Endpoint Manager console.
v You can now perform patch management.

Example script package to install an Endpoint Manager agent on

SUSE Linux
This script package installs an Endpoint Manager agent on a SUSE Linux
Enterprise system and configures an environment variable which is used by the
Endpoint Manager server to group virtual machines.
v Retrieve the Endpoint Manager Server Masthead from the Endpoint Manager
Server machine. If the masthead is not named actionsite.afxm, rename it to
actionsite.afxm.
v Retrieve the appropriate SUSE Linux Enterprise agent installer (.rpm) from
http://support.bigfix.com/install/besclients-nonwindows.html, for example
BESAgent-8.2.1175.0-sle11.x86_64.rpm
v Create the install.sh script as follows, replacing the <SERVER IP> and
<SERVER HOSTNAME> placeholders with the correct IP and host name values
corresponding to the Endpoint Management server machine. If the Endpoint
Manager server port is not the default value of 52311, replace this value with the
correct port number:
# Source the env file
if [ -f "/etc/virtualimage.properties"]; then
. /etc/virtualimage.properties
fi
# install the IEM client package
rpm -ivf /tmp/IEMClient/BESAgent*.rpm
# copy the actionsite masthead
cp /tmp/IEMClient/actionsite.afxm /etc/opt/BESClient
# resolve IEM server shortname to ip address
echo "<SERVER IP><SERVER HOSTNAME>">>/etc/hosts
# Add the IEM Server port 52311 to iptables
if [ -f "/etc/init.d/SuSEfirewall2_init"]; then
# SUSE/SLES host
/etc/init.d/SuSEfirewall2_init status >/dev/null 2>&1
if [ $? -eq 0 ]; then
/etc/init.d/SuSEfirewall2_setup stop
iptables -A INPUT -p tcp --dport 52311 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 52311 -j ACCEPT
/etc/init.d/SuSEfirewall2_setup reload
fi
else
/etc/init.d/iptables status >/dev/null 2>&1
if [ $? -eq 0 ]; then
# save the iptables and then stop it
/etc/init.d/iptables save
/etc/init.d/iptables stop
iptables -A INPUT -p tcp --dport 52311 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 52311 -j ACCEPT
/etc/init.d/iptables save
/etc/init.d/iptables start
fi
fi
# If the _BESCLIENT_GROUP_NAME is set (default is none i.e. ignore)
Chapter 9. Integrating

727

if [ ! "${_BESCLIENT_GROUP_NAME}"== "none"]; then

echo "Group policy to be set to: ${_BESCLIENT_GROUP_NAME}"
echo "[Software\BigFix\EnterpriseClient\Settings\Client\_BESCLIENT_GROUP_NAME]"
>>/var/opt/BESClient/besclient.config
echo "value = ${_BESCLIENT_GROUP_NAME}">>/var/opt/BESClient/besclient.config
fi
# start the IEM client
/etc/init.d/besclient start

v Create the cbscript.json file: Make sure that the name specified in the file
below matches the script package zip name, for example, IEM_8.2.1175.0sle11.x86_64.zip:
[
{
"name": "IEM_8.2.1175.0-sle11.x86_64",
"version": "1.0.0",
"description": "This script package installs the IEM Agent on SUSE 11",
"command": "/bin/sh /tmp/IEMClient/install.sh",
"log": "/tmp/IEMClient",
"location": "/tmp/IEMClient",
"timeout": "0",
"commandargs":"",
"keys":
[
{
"scriptkey": "_BESCLIENT_GROUP_NAME",
"scriptvalue": "",
"scriptdefaultvalue": "none"
}
]
}
]

v The script package name must match the name specified in the cbscript.json
file. Create the script package by zipping together the following files (for
example, IEM_8.2.1175.0-sle11.x86_64.zip) :
actionsite.afxm
The Endpoint Manager Server Masthead.
BESAgent-8.2.1175.0-sle11.x86_64.rpm
The agent installer for SUSE Linux.
install.sh
cbscript.json
v Import the script package zip file into IBM Cloud Orchestrator and keep the
default setting of Executes at virtual system creation.
v Create a pattern containing a SUSE Linux Enterprise part and add the script
package to this part.
v Optional: Configure a Computer Group, in the Endpoint Manager Server
console, to match the proposed _BESCLIENT_GROUP_NAME environment variable
value set when the virtual system is deployed.
v Deploy the pattern. Optional: Specify the value for the _BESCLIENT_GROUP_NAME
environment variable to match the Computer Group configured in the Endpoint
Manager console. By default this value is set to none and is ignored.
v The script package will run when the virtual system is deployed. To verify the
agent installed correctly review the log files.
v After the agent has registered with the Endpoint Manager server, the computer
system information is displayed in the Endpoint Manager console.

728

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v If a group has been configured and set, the computer is also displayed under the
specific group heading in the Endpoint Manager console.
v You can now perform patch management.

Example script package to install an Endpoint Manager agent on

Windows
This script package installs an Endpoint Manager agent on a Windows system and
configures an environment variable which is used by the Endpoint Manager server
to group virtual machines.
v Retrieve the Endpoint Manager Server Masthead from the Endpoint Manager
Server machine. If the masthead is not named actionsite.afxm, rename it to
actionsite.afxm.
v Retrieve the Windows installer file from the IBM Tivoli Endpoint Manager
server in the C:\Program Files (x86)\BigFix Enterprise\BES
Console\BESClientDeploy\BigFixInstallSource\ClientInstaller installation
folder. The file is named setup.exe.
v Create the install.bat script as follows, replacing the <SERVER IP> and
<SERVER HOSTNAME> placeholders with the correct IP and host name values
corresponding to the Endpoint Management Server machine:
REM set the hostname
REM <SERVER IP><SERVER HOSTNAME>
set hostspath=%windir%\System32\drivers\etc\hosts
echo <SERVER IP><SERVER HOSTNAME>>>%hostspath
%REM navigate to the dir
cd C:\\TEMP\\TEMClient
REM check for _BESCLIENT_GROUP_NAME
IF %_BESCLIENT_GROUP_NAME% == ""GOTO NOPATH
:YESPATH
IF %_BESCLIENT_GROUP_NAME% == "none"GOTO NOPATH
REM The _BESCLIENT_GROUP_NAME environment variable was detected.
REM create the clientsettings.cfg file.
REM Group policy to be set to: %_BESCLIENT_GROUP_NAME%
@ECHO _BESCLIENT_GROUP_NAME=%_BESCLIENT_GROUP_NAME%>>clientsettings.cfg
GOTO END
:NOPATH
REM The _BESCLIENT_GROUP_NAME environment variable was NOT detected or set to none.
GOTO END
:END
REM install the TEM client package
setup.exe /s /v/qn

v Create the cbscript.json file. Make sure that the name specified in the file
below matches the script package zip name, for example, IEM_8.2.1175.0windows_setup.zip:
[
{
"name": "IEM_8.2.1175.0-windows_setup",
"version": "1.0.0",
"description": "This script package installs the TEM Client on WIN
"command": "install.bat",
"log": "C:\\TEMP\\TEMClient",
"location": "C:\\TEMP\\TEMClient",
"timeout": "0",
"commandargs":"",
"ostype": "windows",
"keys":

",

Chapter 9. Integrating

729

[
{
"scriptkey": "_BESCLIENT_GROUP_NAME",
"scriptvalue": "",
"scriptdefaultvalue": "none"
}
]
}
]

v The script package name must match the name specified in the cbscript.json
file. Create the script package by zipping together the following files (for
example, IEM_8.2.1175.0-windows_setup.zip) :
actionsite.afxm
The Endpoint Manager Server Masthead.
setup.exe
The agent installer for Windows.
install.bat
cbscript.json
v Import the script package zip file into IBM Cloud Orchestrator and keep the
default setting of Executes at virtual system creation.
v Create a pattern containing a Windows operating system part and add the script
package to this part.
v Optional: Configure a Computer Group, in the Endpoint Manager Server
console, to match the proposed _BESCLIENT_GROUP_NAME environment variable
value set when the virtual system is deployed.
v Deploy the pattern. Optional: Specify the value for the _BESCLIENT_GROUP_NAME
environment variable to match the Computer Group configured in the Endpoint
Manager console. By default this value is set to noneand is ignored.
v The script package runs when the virtual system is deployed. To verify the agent
installed correctly review the log files.
v Once the agent has registered with the Endpoint Manager server the computer
system information is displayed in the Endpoint Manager console.
v If a group has been configured and set, the computer also displays under the
specific group heading in the Endpoint Manager console.
v You can now perform patch management..

Troubleshooting
If the Endpoint Manager agent fails to register with the Endpoint Manager server,
check the following issues:
v The host name where the Endpoint Manager agent is installed must be correctly
resolved by using the ping command from the Endpoint Manager server, and
viceversa. To ping the machine, use the command:
# ping ip_address

where ip_address is:

When located on the Endpoint Manager server, ip_address refers to the host
where the Endpoint Manager agent is installed.
When located on the host where the Endpoint Manager agent is installed,
ip_address refers to the Endpoint Manager server.
v Ensure that Port 52311 is open between the host where the Endpoint Manager is.

730

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Ensure that the agent is running, by executing the following command on the
virtual machine:
# /etc/init.d/besclient status

If the agent is not running, start the agent by executing:

# /etc/init.d/besclient start

v Restart the agent within the virtual system:

# /etc/init.d/besclient stop
# /etc/init.d/besclient start

Note: On Windows, the client is installed as a service.

v Ensure that the host name resolves to the correct IP address. Verify the values in
the hosts file.

Chapter 9. Integrating

731

732

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 10. Reporting

IBM Cloud Orchestrator provides a diverse set of reports that provide specific data
you can use for planning purposes.

Tivoli Common Reporting

Tivoli Common Reporting is provided for reporting of monitoring, metering, and
billing.
v For information about Tivoli Common Reporting, including installation, see the
Jazz for Service Management information center.
v For information about using Tivoli Common Reporting for metering and billing,
see the Administering reports guide in the metering and billing section.
v For information about using Tivoli Common Reporting in IBM Tivoli
Monitoring, see the Tivoli Common Reporting in the IBM Tivoli Monitoring
information center.

Copyright IBM Corp. 2013, 2015

733

734

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 11. Reference

The following topics provide reference information for IBM Cloud Orchestrator.

Using the command-line interface

You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.

About this task

You can download the command-line interface tool from IBM Cloud Orchestrator
to your local computer. You can then run the command-line interface tool from
your local machine to connect to IBM Cloud Orchestrator and run commands
remotely.
In the examples that follow, the command prompt in the Python environment is
represented as three greater than symbols (for example: >>>) The commands that
you enter follow this prompt indicator.
To configure and administer IBM Cloud Orchestrator, use the OpenStack
command-line interface or the Admin Console. For example, you might need to
use the keystone command-line interface to manage authentication and
authorizations, and the glance command-line interface to manage virtual images.
For more information about the OpenStack command-line interface, see the
OpenStack CLI Guide.
Related information:
Python documentation
Linux Download information

Command-line interface overview

The command-line interface tool provides a scripting environment in which you
can run commands to manage IBM Cloud Orchestrator remotely. You can also run
Python scripts or individual Python commands.
The scripting environment is based on Jython, the Java-based implementation of
Python. The Jython interpreter implements some of the Python 2.5.1 language. The
command-line interface uses the Jython interpreter, along with standard Jython
libraries, functions, and classes to help you manage your IBM Cloud Orchestrator.
You can download the command-line interface tool to any local computer running
a supported Windows or Linux operating system, and then point to where IBM
Cloud Orchestrator is running. For more information on downloading the tool, see
Downloading and configuring the command-line interface on page 736.
The command-line interface communicates with the IBM Cloud Orchestrator over a
hypertext transfer protocol secure (HTTPS) session. The command-line interface
does not cache updates and it has only minimal caching for reads. If the machine
on which the command-line interface is running loses connectivity to port 443 of
the machine where the Workload Deployer component is running, you can
perform only rudimentary operations.
Copyright IBM Corp. 2013, 2015

735

The IBM Cloud Orchestrator command-line interface can run in both interactive
and batch modes. For more information about initializing the command-line
interface for either batch or interactive mode, see Invoking the command-line
interface on page 737.
Related information:
Jython
Python documentation

Downloading and configuring the command-line interface

Download the command-line interface to your local computer to perform
administrative tasks onIBM Cloud Orchestrator.

Before you begin

Ensure that the local computer to which you are downloading the command-line
interface tool is running a supported Windows or Linux operating system.
Ensure that you have Java Runtime Environment (JRE) Version 6 installed on the
local computer, and that either the JAVA_HOME or the PATH environment variable is
set to the location of your JRE.

About this task

Complete the procedure in this task to download and install the command-line
interface tool.

Procedure
1. Download thecommand-line interface tool from http://<Central Server
3>/downloads/cli/ in your IBM Cloud Orchestrator installation.
2. Save the .zip file. On your local hard disk drive, save the .zip file.
3. Open the .zip file. Expand the contents of this .zip file to a directory on your
hard disk. When expanded, the .zip file creates a directory tree under a single
top-level directory, the deployer.cli directory.
4. Ensure that either the JAVA_HOME or the PATH environment variable is set to the
location of your JRE.
5. Optional: If you are running the Windows Server 2003 operating system or the
Windows Server 2008 operating system, perform this step.
In the deployer.cli directory, create a registry file in the lib\<version> with
the following line:
python.os=nt

This causes Jython to bypass the normal operating system detection logic and
treat the system as a Windows machine.
By default, the only thing in the lib directory is a <version> subdirectory that
matches level of the product from which the CLI was downloaded. If you use
this CLI installation to communicate with products at different version levels,
then there is one subdirectory under the /lib directory for each of these
version levels and you must copy the registry file into each of these
subdirectories.
Example: \lib\3.0.0.0-12345\registry

736

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Results
You have installed the IBM Cloud Orchestrator command-line interface in the bin
directory using the shell scripts (deployer.bat on Windows and deployer on
Linux). After the CLI is installed, you can verify the install by running
deployer.bat on Windows or deployer on Linux from the bin directory. If the
environment is set up correctly, then an informational message tells you that the
command-line interface is working and provides further details about using the
command-line interface.

What to do next
Invoke the command-line interface. For more information, see Invoking the
command-line interface.

Invoking the command-line interface

To perform administrative functions for IBM Cloud Orchestrator, you can invoke
the command-line interface in either interactive mode or batch mode from a local
machine running either Windows or Linux operating systems.

Before you begin

You must have downloaded and extracted the command-line interface using the
instructions in Downloading and configuring the command-line interface on
page 736. If you recently upgraded your IBM Cloud Orchestrator then download
the new version of the command-line interface. Downloading a new version of the
command-line interface ensures new functionality works as expected and you also
get the latest samples.

About this task

The IBM Cloud Orchestrator command-line interface is invoked on your local
machine. You can run the command-line interface in interactive mode or in batch
mode.
A command-line interface session uses the timeout value specified on IBM Cloud
Orchestrator. When a user session expires, they are prompted to re-enter their
userid and password. If the DEPLOYER_REAUTHENTICATE environment variable
is set, then a new session is automatically started for the user when an existing
session expires. If the userid and password entered to start a session are not
correct, then you are re-prompted for new values.

Procedure
v Invoke the command-line interface in interactive mode. To invoke the
command-line interface in interactive mode, use the following parameters:
-u <userid> or
--userid
This optional parameter specifies the userid to authenticate to IBM
Cloud Orchestrator. If the userid parameter is not specified, the
command-line interface uses the value of the DEPLOYER_USERID
environment variable to determine the userid. When the userid is not
included on the command-line and the environment variable is not set,
you are prompted to enter a userid.

Chapter 11. Reference

737

-p <password> or
--password
This optional parameter specifies the password used to authenticate to
IBM Cloud Orchestrator. If the password parameter is not specified, the
command-line interface uses the value of the DEPLOYER_PASSWORD
environment variable to determine the password. When the password is
not included on the command-line and the environment variable is not
set, you are prompted to enter a password.
Note: -p is case sensitive.
-h <hostname> or
--hostname
This required parameter indicates the host name or IP address of the
machine where the Workload Deployer component is installed. If you
specify this option, do not use the URL to access the Web interface. If
this parameter is not specified, the command-line interface uses the
value of the DEPLOYER_HOSTNAME environment variable to
determine the host name.
Note: You must specify only the host name or IP address, not the full URL used
to access the web user interface.
$ deployer -h mydeployer.mycompany.com -u username -p password

You have invoked the IBM Cloud Orchestrator command-line interface in

interactive mode.
v Invoke the command-line interface in batch mode. To invoke the command-line
interface in batch mode, use the following optional parameters in addition to
those parameters used to start the command-line interface in interactive mode:
-c <command>
Use this optional parameter to pass a command to the command line to
be run. You can specify this option multiple times to run multiple
commands. If the command is a Jython expression, it is evaluated and
the command-line interface displays the result. If the command is a
Jython statement, it is run but no output is generated unless the
statement itself causes output to be generated.
Note: Do not specify this parameter if you want to run the
command-line interface in interactive mode.
$ deployer -h mydeployer.mycompany.com -u joeadmin
-p password -c "deployer.hypervisors"

-f <script_file> <arg>*
Use this optional parameter to cause the command line to run the
specified Jython script file with the specified arguments. Any arguments
following the script file name are passed to the Jython script. Only one
-f parameter can be specified on the command line. You are running the
command-line interface in batch mode.
$ deployer -h mydeployer.mycompany.com -u joeadmin
-p password -f sampleScript.jy arg1 arg2 arg3

On Linux, you can make the shell automatically use the IBM Cloud
Orchestrator command to execute your Jython scripts. If the IBM Cloud
Orchestrator command is on your PATH, insert the following line at the
top of your script to have the shell execute it using the command-line
interface:

738

IBM Cloud Orchestrator 2.4.0.2: User's Guide

#!/usr/bin/env deployer

Passing commands to the command line by any of these methods (on the
command line using the -c parameter, or in a script file specified using the -f
parameter), support the same Jython scripting language.

Results
After completing these steps, the command-line interface is running in interactive
mode or the script or command you invoked is now running.

What to do next
You are ready to use the command-line interface. You can get help for any
command, attribute, or method on the command-line interface using the
instructions provided in the Getting help on the command-line interface. For a
list of the available objects to be used in the command-line interface, see
Command-line interface resource object reference on page 740. A set of sample
scripts that demonstrate some of the command-line interface function are located
in the <cli_install_dir>\samples directory.

Getting help on the command-line interface

As you perform administrative functions for IBM Cloud Orchestrator using the
command-line interface, you can get help for all resources.

Before you begin

You must have downloaded and initialized the command-line interface using the
instructions in Downloading and configuring the command-line interface on
page 736 and Invoking the command-line interface on page 737.

About this task

You can get help for any IBM Cloud Orchestrator resources, attributes, and
methods on the command-line interface. This task provides basic information
about options for invoking the command-line interface help function.
Use the help command to get help for command syntax, available commands, and
using interactive mode. To get help, start the command-line interface in interactive
mode. To run the command-line interface tool in interactive mode, initialize with
the required parameters (-u -p and -h as discussed in more detail in Invoking the
command-line interface on page 737), but do not include the -c or -f parameters.
Then enter help, as shown in the following example:
$ deployer -h mydeployer.mycompany.com -u joeadmin -p password
>>> help

The help command shown in the previous example is a Jython function. When it is
used as shown in the previous example, it provides a high-level overview of the
command line environment and instructions for accessing help on more specific
topics.

Procedure
v Invoke general help.
When used with no parentheses and no parameters, the help command provides
general help for using the IBM Cloud Orchestrator command-line interface.

Chapter 11. Reference

739

In interactive mode, you can invoke deployer.help without the package prefix,
as shown in the following example:
>>> help

v Invoke help for the package. Help is available for the IBM Cloud Orchestrator
package.
To get help for the IBM Cloud Orchestrator package, use the following
command:
>>> help(deployer)

When invoked with a parameter, the help function provides detailed information
about the specified package, module, function, or property. Information about
invoking help for each resource is available in the reference information for that
resource.
v Invoke detailed help about a specific topic.
Pass a single parameter to the help function to get more detailed help about a
specific topic. For example, to see detailed help for how to work with
hypervisors in the command-line interface, enter the following command:
>>> help(deployer.hypervisors)

The deployer prefix is used to group all the IBM Cloud Orchestrator-specific
Jython functions into a single package to reduce the chances of name collisions
with functions and variables in your own scripts.

Results
Detailed or general help is displayed.

What to do next
You can continue to use the command-line interface guided by the information in
the help function.

Command-line interface resource object reference

Anything that can be managed in IBM Cloud Orchestrator is a resource object on
the command-line interface. The IBM Cloud Orchestrator command-line interface
manages different types of resources, for example patterns, virtual images, and
virtual system instances.

AddOn command-line interface reference

You can administer additions in the catalog using the IBM Cloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.

AddOns object
An AddOns object represents the collection of add-ons defined to IBM Cloud
Orchestrator. Objects of this type are used to create, delete, iterate over, list and
search for add-ons on the product. To get help for the AddOns object, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.addons)

740

IBM Cloud Orchestrator 2.4.0.2: User's Guide

AddOn object
An AddOn object represents a particular add-on defined in IBM Cloud Orchestrator.
Use the AddOn object to query and manipulate the add-on definition in the product.
Attributes of the add-on and relationships between the add-on and other resources
in the product are represented as Python attributes on the AddOn object. Manipulate
these Python attributes using standard Python mechanisms to make changes to the
corresponding data in the product. To get help for the AddOn object, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.addon)

AddOn attributes
The AddOn object has the following attributes:
acl

The access control list for this add-on. For additional help on using this
object, enter the following command:
>>> help(deployer.acl)

This field is read-only.

archive
An archive object represents the archive file associated with a particular
add-on in the product. This object provides mechanisms to query and
manipulate the add-on archive in the product. This field is read-only. For
more information, see Archive methods on page 742.
command
The command to be run for this add-on.
commandargs
The arguments that are passed to the command.
created
The creation time of the add-on, as the number of seconds since midnight
January 1, 1970 UTC. When the add-on is displayed, this value is shown as
the date and time in the local timezone. This field is read-only.
currentstatus
The current status of the add-on.
currentstatus_text
The textual representation of the currentstatus. This field is read-only.
description
The description of the add-on.
environment
The environment property holds the add-on keys and default values for the
add-on. It is used much like a Python dict object, as shown in the
following example:
>>> myaddon.environment
{
"addonkey1": "value for addonkey1",
"addonkey2": "value for addonkey2"
}
>>> myaddon.environment[addonkey1]
value for addonkey1
>>> myaddon.environment[foo] = bar
>>> myaddon.environment
{
"foo": "bar",
Chapter 11. Reference

741

"addonkey1": "value for addonkey1",

"addonkey2": "value for addonkey2"
}
>>> del myaddon.environment[foo]
>>> myaddon.environment
{
"addonkey1": "value for addonkey1",
"addonkey2": "value for addonkey2"
}

This field is read-only. See Environment methods on page 743 for more
information.
id

The ID of the add-on. This field is read-only.

label

The label for the add-on. This field is read-only.

location
The directory, on the virtual machine, into which files for this add-on
package are to be placed.
log

The directory, on the virtual machine, that is to contain the log files
generated by this add-on.

name

The name associated with this add-on. Each add-on must have a unique
name.

timeout
The maximum amount of time to wait for this add-on to finish running on
a virtual machine. Specify the timeout as the number of milliseconds to
wait, or 0 to wait indefinitely for the add-on to complete.
type

The type of add-on. This attribute must have a string value equal to one of
the following constants:
v deployer.DISK_ADDON
v deployer.NIC_ADDON
v deployer.USER_ADDON

updated
Thd time the add-on was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the add-on is displayed, this value
is shown as the date and time in the local timezone. This field is read-only.

Archive methods
The Archive object has the following attributes:
get

This method retrieves the archive currently associated with the add-on.
This method has one required parameter that indicates where the add-on
archive should be saved. It can be either of the following values:
v A string containing the name of a file in which to save the archive. The
.zip file type is automatically appended to the filename if the filename
does not end in .zip.
v A Python file object. You must ensure that the file object can correctly
handle binary data.
The add-on archive is returned in a zip file format, as shown in the
following example
>>> myaddon.archive.get(/path/to/foo.zip)

742

IBM Cloud Orchestrator 2.4.0.2: User's Guide

__lshift__
This method is invoked implicitly when the Archive object is used as the
left argument of a left shift operator (<<). It calls set() with the right
argument of the operator, as shown in the following example:
>>> myaddon.archive << /path/to/file

__rshift__
This method is invoked implicitly when the Archive object is used as the
left argument of a right shift operator (<<). It calls get() with the right
argument of the operator, as shown in the following example:
>>> myaddon.archive >> /path/to/file.zip

This method sets the archive associated with the add-on. It has one
required parameter that indicates the source of the add-on archive to be
uploaded. It maycan be either of the following values:

set

v A string containing the name of a file from which to get the archive.
v A Python file object.
You must ensure that the file object can correctly handle binary data, as
shown in the following example:
>>> myaddon.archive.set(/path/to/foo)

Environment methods
The Environment object has the following attributes:
isDraft
Indicates if this add-on is in draft mode.
isReadOnly
Indicates if this add-on is read-only.
makeReadOnly
Makes this add-on read-only. When the add-on is read-only, it cannot be
modified.
Creates a copy of this add-on with all of the same files, fields, and settings.
The new add-on has the name provided and an empty ACL.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related information:
clone

Jython
Python documentation

Chapter 11. Reference

743

Audit logging command-line interface reference

You can collect your audit reports by using the command-line interface tool.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.
You can gather your reports by working with the Audit object on the
command-line interface.

Audit object
An Audit object represents the audit logs stored on IBM Cloud Orchestrator.
To get help on the command-line interface for the Audit object, pass the name of
the object as an argument to the help() function. See the following example for
details:
>>> help(deployer.audit)

For more information about working with resource objects on the command-line
interface, see Resources on the command line on page 843.

Audit methods
You can use the following methods on an Audit object:
get("file", start=start_time, end=end_time, tz="time_zone", size=size)
This method downloads an audit log from the product in a .zip file. Use
the size parameter to specify the maximum number of audit records that
you want to download. You can use other parameters to filter your record
set, according to the time frame in which the records were logged.
Parameter descriptions:
v file - A file object or file name used to store the audit log. If a file name
is specified, then .zip is automatically appended if the specified name
does not end in .zip.
v start_time - The earliest timestamp to be included in the audit data,
specified as the number of seconds since midnight, January 1, 1970 UTC.
Floating point values can be specified to indicate fractional seconds. The
start parameter is optional.
v end_time - The latest timestamp to be included in the audit data,
specified as the number of seconds since midnight, January 1, 1970 UTC.
Floating point values can be specified to indicate fractional seconds. The
end parameter is optional.
v time_zone - The time zone of the time frame that you specify in the start
and end parameters. The tz parameter is optional.
v size - The maximum number of records to be written to the .zip file. You
can request up to 20,000 records. If you specify a greater number, the
product automatically resets your request to 20,000 records, and writes
that number of records to the .zip file.
For example:
deployer.audit.get("my.zip",start=1321391040,end=1321911000,tz="est",size=10000)

744

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Returned audit data

The .zip file that you download contains the following files:
v license-audit.csv - Currently not supported.
v pvu-audit.csv - Currently not supported.
v audit-events.zip - This file contains the following files:
audit-events.csv - This file contains the audit event records that you just
specified for download.
audit-events-signed-events-checksum - Contains the digital signature that
verifies both the integrity and authenticity of your audit data. Archive this file
along with your event records.
audit-events-record-IDs
audit-events-signed-record-IDs
Note: The last two files contain data that you must use in a subsequent task,
to delete your event records and thus free storage resources.
The most important files for analysis and maintaining an audit trail are
appliance-audit.csv, audit-events.csv, and audit-events-signed-eventschecksum.
Related tasks:
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related information:
Jython
Python documentation

Cloud group command-line interface reference

You can work with cloud groups using the IBM Cloud Orchestrator command-line
interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.

Clouds object
A clouds object represents a collection of cloud groups that are defined to IBM
Cloud Orchestrator. Objects of this type are used to delete, iterate over, list and
search for cloud groups on IBM Cloud Orchestrator.
To get help for the clouds object on the command-line interface, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.clouds)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Cloud object
A cloud object represents a particular cloud group that is defined in IBM Cloud
Orchestrator. Use the cloud object to query and manipulate the cloud group
definition in the product. Attributes of the cloud group, and relationships between
Chapter 11. Reference

745

the cloud group and other resources on IBM Cloud Orchestrator, are represented as
Jython attributes on cloud objects. Manipulate these Jython attributes using
standard Jython mechanisms to change the corresponding data on the IBM Cloud
Orchestrator.
Cloud objects can have many hypervisors objects.
To get help for the cloud object on the command-line interface, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.cloud)

Cloud attributes
The cloud object supports the following attributes:
acl

Access control list for this cloud group. For additional help on using this
object, enter:
>>> help(deployer.acl)

address
The network address or host name is retrieved from the hypervisor
manager each time.
created
Creation time of the cloud group, as number of seconds since midnight,
January 1, 1970 UTC. When the cloud group is displayed, this value is
shown as the date and time in the local time zone. This field is read-only.
currentstatus
The status of the cloud object. This field contains an eight character string
value that is generated by the product.
currentstatus_text
This attribute is a string representation of the currentstatus attribute in
the preferred language of the requester and is automatically generated by
the product. This field is read-only.
defaultcloud
Indicates if this cloud group is the default cloud group used by IBM Cloud
Orchestrator. This attribute is read-only.
description
Description of the cloud group. This field is a string and can be edited.
endpointtype
Specifies the type of endpoints managed by the cloud object. This
read-only value is determined based on the target endpoints currently
added to the Cloud object. The value of the endpoint type can be one of
the following:
v Hypervisor: The cloud object manages one or more hypervisor
endpoints.
v Pool: The cloud object manages a pool.
v Cluster: The cloud object manages a cluster.
v None: The cloud object does not manage any endpoints.
v Mixed: The cloud object manages endpoints of multiple types.
id

746

The ID of the cloud group. This field is read-only.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

name

The name associated with this cloud group. Each cloud group must have a
unique name.

owner

A user object that references the owner of this cloud group. For more
information about the properties and methods supported by user objects,
enter:
>>> help(deployer.user)

type

The type of this cloud group. It must be manager.

updated
The time the cloud group was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the cloud group is displayed, this
value is shown as the date and time in the local time zone. This attribute is
read-only.
vendor The type of hypervisors this cloud group contains. Valid value is
OpenStack.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Cloud methods
The cloud object has the following methods associated with it:
discover()
Forces IBM Cloud Orchestrator to rediscover the network and storage to
which the hypervisor is attached. This method accepts a single optional
parameter that allows you to specify to opt-in or opt-out the discovered
network and storage. The following values are valid for this parameter:
T

Opt-in discovered network and storage

Opt-out discovered network and storage

The default is to opt-in the discovered network and storage

getTargets()
This method returns the list of targets for a cloud. The returned targets are
either assigned to the given cloud or associated to a given cloud. Targets
assigned to the given cloud contain a cloudid attribute.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related information:
Jython
Python documentation

Chapter 11. Reference

747

Environment profiles command-line interface reference

You can work with environment profiles on the IBM Cloud Orchestrator
command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 735.
You can use the following resources to work with environment profiles:
EnvironmentProfiles
Represents the collection of environment profiles defined to IBM Cloud
Orchestrator. For more information, see Environment profiles on the
command-line interface on page 749.
EnvironmentProfileClouds
Use the EnvironmentProfileClouds object to manipulate the clouds and IP
groups associated with an environment profile. For more information
about environment profile clouds, see Environment profile clouds on the
command-line interface on page 752.
EnvironmentProfileCloudIPGroups
Use the EnvironmentProfileCloudIPGroups object to manipulate the IP
groups associated with a cloud in an environment profile. For more
information about environment profile cloud IP groups, see Environment
profile cloud IP groups on the command-line interface on page 755.
User

A user can own environment profiles.

Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related tasks:
Managing environment profiles on page 354
You can use environment profiles to control some aspects of your deployment. You
can use environment profiles to group related deployment configuration options
together and deploy from a single pattern.
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related reference:
Environment profiles on the command-line interface on page 749
You can work with the environment profiles on the IBM Cloud Orchestrator
command-line interface.
Environment profile clouds on the command-line interface on page 752
You can work with environment profile clouds on the IBM Cloud Orchestrator
command-line interface.
Environment profile cloud IP groups on the command-line interface on page 755
You can work with the environment profile cloud IP group objects on the IBM
Cloud Orchestrator command-line interface.
Related information:
Jython
Python documentation

748

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Environment profiles on the command-line interface:

You can work with the environment profiles on the IBM Cloud Orchestrator
command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 735.
EnvironmentProfiles object
An EnvironmentProfiles object represents the collection of environment profiles
defined to IBM Cloud Orchestrator. Objects of this type are used to create, delete,
iterate over, list and search for environment profiles in IBM Cloud Orchestrator.
You can work with EnvironmentProfiles objects on the command line and help is
available. To get help for the EnvironmentProfiles object, pass it as an argument to
the help() function, as shown in the following example:
>>> help(deployer.environmentprofiles)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
EnvironmentProfile object
An EnvironmentProfile object represents a particular environment profile defined
to IBM Cloud Orchestrator. Use the EnvironmentProfile object to query and
manipulate the environment profile definition in the product. Attributes of the
EnvironmentProfile object on the IBM Cloud Orchestrator, are represented as
Jython attributes on the EnvironmentProfile object. Relationships between the
environment profile and other resources are also represented as Jython attributes
on the EnvironmentProfile object. You can manipulate these Jython attributes
using standard Jython mechanisms to change the corresponding data on the IBM
Cloud Orchestrator.
You can work with EnvironmentProfile objects on the command line and help is
available. To get help for the EnvironmentProfile object, pass it as an argument to
the help() function, as shown in the following example:
>>> help(deployer.environmentprofile)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
EnvironmentProfiles attributes
The EnvironmentProfiles object has the following attributes:
acl

The access control list for this environment profile. For additional help on
using this object, see ACL object on page 862 or enter the following
command:
>>> help(deployer.acl)

clouds An object that manipulates the clouds and IP groups associated with an
environment profile. For additional help on using this object, see
Environment profile clouds on the command-line interface on page 752
or enter the following command:
>>> help(deployer.environmentprofileclouds)
Chapter 11. Reference

749

created
The creation time of the environment profile, as number of seconds since
midnight, January 1, 1970 UTC. When the environment profile is
displayed, this value is shown as the date and time in the local time zone.
currentmessage
The message associated with the status of the environment profile.
currentmessage_text
The textual representation of the currentmessage attribute.
currentstatus
The status of the environment profile.
currentstatus_text
The textual representation of the currentstatus attribute.
description
A description of the environment profile.
environment
The environment the profile represents. The following values are valid for
the environment attribute:
v deployer.environmentprofile.ALL_ENVIRONMENT
v deployer.environmentprofile.DEVELOPMENT_ENVIRONMENT
v deployer.environmentprofile.TEST_ENVIRONMENT
v deployer.environmentprofile.QUALITY_ASSURANCE_ENVIRONMENT
v
v
v
v
id

deployer.environmentprofile.PERFORMANCE_ENVIRONMENT
deployer.environmentprofile.RESEARCH_ENVIRONMENT
deployer.environmentprofile.PRODUCTION_ENVIRONMENT
deployer.environmentprofile.PRE_PRODUCTION_ENVIRONMENT

The ID of the environment profile.

ipsource
Indicates the source of IP addresses for this environment profile. The
following values are valid for the ipsource attribute:
deployer.environmentprofile.WEBSPHERE_DEPLOYER_IPSOURCE
IBM Cloud Orchestrator selects the IP addresses.
deployer.environmentprofile.PATTERN_DEPLOYER_IPSOURCE
The user who is deploying the pattern provides the IP address.
Important: If this option is used, the person deploying the pattern
cannot specify an IP address that is contained within the IP groups
defined in IBM Cloud Orchestrator.
memory_cap
The maximum amount of memory that deployers using this environment
profile can consume.
memory_inuse
The amount of memory that deployers have reserved using in this
environment profile. This field is read only.
memory_reserved
The amount of memory that deployers are using in this environment
profile. This field is read only.
name

750

The name of the environment profile.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

owner

A User object that references the owner of this environment profile. For
more information about the properties and methods supported by User
objects, enter the following command:
>>> help(deployer.user)

pcpu_cap
The maximum number of available physical CPUs that the deployers using
this environment profile can consume.
pcpu_inuse
The number of physical CPUs that deployers are using in this environment
profile. This field is read only.
pcpu_reserved
The number of physical CPUs that deployers have reserved using this
environment profile. This field is read only.
platform
The type of hypervisors this environment profile supports on deployments.
Valid value is OpenStack.
storage_cap
The maximum amount of storage that deployers using this environment
profile can consume.
storage_inuse
The amount of storage that deployers have reserved using in this
environment profile.
storage_reserved
The amount of storage that deployers are using in this environment profile.
This field is read only.
updated
The time the environment profile was last updated, as number of seconds
since midnight, January 1, 1970 UTC. When the environment profile is
displayed, this value is shown as the date and time in the local time zone.
vcpu_cap
The maximum number of virtual CPUs that deployers using this
environment profile can consume.
vcpu_inuse
The number of virtual CPUs that deployers have reserved using in this
environment profile. This field is read only.
vcpu_reserved
The number of virtual CPUs that deployers are using in this environment
profile.
vmname_pattern
The pattern used to generate virtual machine names. Various predefined
attributes can be included in the virtual machine name by including the
following strings in the vmname_pattern attribute:
${hostname}
Replaced with the host name of the virtual machine.
${n-counter}
Replaced with a counter of n digits. The n variable in this string is
a placeholder for the number you supply.

Chapter 11. Reference

751

${vs-name}
Replaced with the name of the virtual system instance.
For example, a vmname_pattern attribute with the following value:
${vs-name} - ${hostname} - ${4-counter}

results in virtual machine names like the names shown in the following
example:
My VS - myhostname - 0017

EnvironmentProfiles methods
The EnvironmentProfiles object has the following method:
Creates a copy of this environment profile with the same settings. The new
environment profile has the name provided as well as an empty ACL.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
clone

Related tasks:
Managing environment profiles on page 354
You can use environment profiles to control some aspects of your deployment. You
can use environment profiles to group related deployment configuration options
together and deploy from a single pattern.
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related reference:
Environment profiles command-line interface reference on page 748
You can work with environment profiles on the IBM Cloud Orchestrator
command-line interface.
Related information:
Jython
Python documentation
Environment profile clouds on the command-line interface:
You can work with environment profile clouds on the IBM Cloud Orchestrator
command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 735.
EnvironmentProfileClouds object
The EnvironmentProfileClouds object manipulates the clouds and IP groups
associated with an environment profile. This object behaves much like a dict object
with Cloud objects as keys. See EnvironmentProfileClouds methods on page 753
for more information. References to these objects can be obtained using the clouds
attributes of EnvironmentProfile objects.

752

IBM Cloud Orchestrator 2.4.0.2: User's Guide

EnvironmentProfileClouds methods
The EnvironmentProfileClouds object has the following methods:
addCloud
Adds a cloud group to the list of cloud groups for an environment profile.
This method accepts the following parameters:
v A Cloud object that represents the cloud group to be added.
v An optional alias for the cloud in this environment profile. If no alias is
provided, the name of the cloud group is used.
clear

Dissociates all the cloud groups from this environment profile.

__contains__
Indicates if the specified cloud group is associated with this environment
profile. This method is called automatically when you use the Python in
operator.
__delitem__
Dissociates a cloud group from this environment profile. This method is
called automatically when you use the Python del statement.
get

Returns an EnvironmentProfileCloud object that describes how a cloud

group is used in this environment profile. This method accepts the same
parameters as thedict object method of the same name:
v A Cloud object representing the cloud group about which information is
to be returned
v An optional default value that is returned if the cloud group is not used
by the environment profile

__getitem__
Returns an EnvironmentProfileCloud object that describes how a cloud
group is used in this environment profile. This method accepts a single
parameter that must be a Cloud object representing the cloud group about
which information is to be returned. This method is started automatically
when you access an item using the Python [] syntax.
has_key
Indicates if the specified cloud group is associated with this environment
profile. This method accepts a single parameter that must be a Cloud object
representing the cloud group about which information is to be returned.
items

Returns a list of (Cloud, EnvironmentProfileCloud) tuples that describe the

cloud groups associated with the environment profile.

__iter__
Returns an iteration over Cloud objects representing the cloud groups in
the environment profile.
iteritems
Returns an iteration over (Cloud, EnvironmentProfileCloud) tuples
representing the cloud group associated with the environment profile.
iterkeys
Returns an iteration over Cloud objects representing the cloud groups in
the environment profile.
itervalues
Returns an iteration over the EnvironmentProfileCloud objects associated
with the environment profile.

Chapter 11. Reference

753

keys

Returns a list of Cloud objects representing the cloud groups in the

environment profile.

__len__
Returns the number of cloud groups associated with the environment
profile.
__repr__
Returns a string representation of the cloud groups and IP groups
associated with the environment profile.
__setitem__
Associates a cloud group with the environment profile and assigns an alias
to it. This method is called automatically when you assign a value to an
item in an EnvironmentProfileClouds object. The key for the item must be
a Cloud object and the assigned value must be a string, as shown in the
following example:
>>> myep = deployer.environmentprofiles[My profile][0]
>>> mycloud = deployer.clouds[My cloud][0]
>>> myep.clouds[mycloud] = alias for my cloud

__str__
Returns a string representation of the cloud groups and IP groups
associated with the environment profile.
__unicode__
Returns a string representation of the cloud groups and IP groups
associated with the environment profile.
values Returns a list of the EnvironmentProfileCloud objects associated with the
environment profile.
EnvironmentProfileCloud object
An EnvironmentProfileCloud object is used to access and modify information
about a particular cloud group in an environment profile. See
EnvironmentProfileCloud methods and EnvironmentProfileCloud attributes on
page 755 for additional information about individual attributes and methods.
EnvironmentProfileCloud methods
The EnvironmentProfileCloud object has the following methods:
__eq__
This method is used automatically by Python to determine if two
EnvironmentProfileCloud objects are equal. That is, if they represent the
same cloud in the same environment profile.
__nonzero__
This method is used by Python whenever an EnvironmentProfileCloud
object is used in a boolean context. It always returns True.
__repr__
This method returns a string representation of the
EnvironmentProfileCloud object and the IP groups it contains.
__str__
This method returns a string representation of the
EnvironmentProfileCloud object and the IP groups it contains.

754

IBM Cloud Orchestrator 2.4.0.2: User's Guide

__unicode__
This method returns a string representation of the
EnvironmentProfileCloud object and the IP groups it contains.
EnvironmentProfileCloud attributes
The EnvironmentProfileCloud object has the following attributes:
alias

The alias attribute can be used to examine and modify the alias assigned to
a cloud group in an environment profile. Its value must be a string.

ipgroups
The ipgroups attribute references an EnvironmentProfileClouds object that
contains additional information about how the IP groups within the cloud
group are used by the environment profile. For additional help on using
this object, enter the following command:
>>> help(deployer.environmentprofilecloudipgroups)

Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related tasks:
Managing environment profiles on page 354
You can use environment profiles to control some aspects of your deployment. You
can use environment profiles to group related deployment configuration options
together and deploy from a single pattern.
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related reference:
Environment profiles command-line interface reference on page 748
You can work with environment profiles on the IBM Cloud Orchestrator
command-line interface.
Related information:
Jython
Python documentation
Environment profile cloud IP groups on the command-line interface:
You can work with the environment profile cloud IP group objects on the IBM
Cloud Orchestrator command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 735.
EnvironmentProfileCloudIPGroups object
An EnvironmentProfileCloudIPGroups object manipulates the IP groups associated
with a cloud in an environment profile. This object behaves much like a dict object
with IPGroup objects as keys. See EnvironmentProfileCloudIPGroups methods on
page 756 for additional information about methods. References to these objects can
be obtained with the ipgroups attributes of EnvironmentProfileCloud objects.
Chapter 11. Reference

755

EnvironmentProfileCloudIPGroups methods
The EnvironmentProfileCloudIPGroups object has the following methods:
addIPGroup
Adds an IP group to the list of IP groups for a cloud in an environment
profile. This method accepts the following parameters:
v An IPGroup object that represents the IP group to be added
v An optional alias for the IP group in this environment profile. If no alias
is provided, the name of the IP group is used.
clear

Dissociates all IP groups from this cloud group in the environment profile.

__contains__
Indicates if the specified IP group is associated with this cloud group in
the environment profile. This method is called automatically when you use
the Python in operator.
__delitem__
Dissociates an IP group from a cloud group in this environment profile.
This method is called automatically when you use the Python del
statement.
get

Returns an EnvironmentProfileCloudIPGroup object that describes how an

IP group is used in this environment profile. This method accepts the same
parameters as the dict method of the same name:
v An IPGroup object representing the IP group about which information is
to be returned
v An optional default value that is returned if the IP group is not used by
this cloud in the environment profile.

__getitem__
Returns an EnvironmentProfileCloudIPGroup object that describes how an
IP group is used in this environment profile. This method accepts a single
parameter that must be an IPGroup object representing the IP group about
which information is to be returned. This method is started automatically
when you access an item using the Python [] syntax.
has_key
Indicates if the specified IP group is associated with this cloud in the
environment profile. This method accepts a single parameter that must be
an IPGroup object representing the IP group about which information is to
be returned.
items

Returns a list of (IPGroup, EnvironmentProfileCloudIPGroup) tuples that

describe the IP groups associated with this cloud group in the environment
profile.

__iter__
Returns an iteration over IPGroup objects representing the IP groups
associated with this cloud group in the environment profile.
iteritems
Returns an iteration over (IPGroup, EnvironmentProfileCloudIPGroup)
tuples representing IP groups associated with this cloud group in the
environment profile.
iterkeys
Returns an iteration over IPGroup objects representing the IP groups
associated with this cloud group in the environment profile.

756

IBM Cloud Orchestrator 2.4.0.2: User's Guide

itervalues
Returns an iteration over the EnvironmentProfileCloudIPGroup objects
associated with the environment profile cloud group.
keys

Returns a list of IPGroup objects representing the IP groups in the

environment profile cloud group.

__len__
Returns the number of IP groups associated with the environment profile
cloud group.
__repr__
Returns a string representation of the IP groups associated with the
environment profile cloud group.
__setitem__
Associates an IP group with the environment profile cloud group and
assigns an alias to it. This method is called automatically when you assign
a value to an item in an EnvironmentProfileCloudIPGroups object. The key
for the item must be an IPGroup object and the assigned value must be a
string, as shown in the following example:
>>>
>>>
>>>
>>>

myep = deployer.environmentprofiles[My profile][0]

mycloud = deployer.clouds[My cloud][0]
myipg = deployer.ipgroups[My ip group][0]
myep.clouds[mycloud].ipgroups[myipg] = alias for my ip group

__str__
Returns a string representation of the IP groups associated with the
environment profile cloud group.
__unicode__
Returns a string representation of the IP groups associated with the
environment profile cloud group.
values Returns a list of the EnvironmentProfileCloudIPGroup objects associated
with the environment profile cloud group.
EnvironmentProfileCloudIPGroup object
An EnvironmentProfileCloudIPGroup object is used to access and modify
information about a particular IP group associated with a cloud group in an
environment profile. See EnvironmentProfileCloudIPGroup methods and
EnvironmentProfileCloudIPGroup attributes on page 758 for additional
information about methods and attributes.
EnvironmentProfileCloudIPGroup methods
The EnvironmentProfileCloudIPGroup object has the following methods:
__eq__
This method is used automatically by Python to determine if two
EnvironmentProfileCloudIPGroup objects are equal. That is, if they
represent the same IP group in the same cloud in the same environment
profile.
__nonzero__
This method is used by Python whenever an
EnvironmentProfileCloudIPGroup object is used in a boolean context. It
always returns True.

Chapter 11. Reference

757

__repr__
This method returns a string representation of the
EnvironmentProfileCloudIPGroup object.
__str__
This method returns a string representation of the
EnvironmentProfileCloudIPGroup object.
__unicode__
This method returns a string representation of the
EnvironmentProfileCloudIPGroup object.
EnvironmentProfileCloudIPGroup attributes
The EnvironmentProfileCloudIPGroup object has the following attributes:
The alias attribute can be used to examine and modify the alias assigned to
the IP group in a cloud group for an environment profile. The value for
this attribute must be a string.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
alias

Related tasks:
Managing environment profiles on page 354
You can use environment profiles to control some aspects of your deployment. You
can use environment profiles to group related deployment configuration options
together and deploy from a single pattern.
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related reference:
Environment profiles command-line interface reference on page 748
You can work with environment profiles on the IBM Cloud Orchestrator
command-line interface.
Related information:
Jython
Python documentation

Hypervisor command-line interface reference

You can work with hypervisors on the IBM Cloud Orchestrator command-line
interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.

Hypervisors object
A hypervisors object represents the collection of hypervisors defined to IBM Cloud
Orchestrator. Objects of this type are used to delete, iterate over, list and search for
hypervisors on IBM Cloud Orchestrator.

758

IBM Cloud Orchestrator 2.4.0.2: User's Guide

You can work with hypervisors objects on the command line and help is available.
To get help for the hypervisors object, pass it as an argument to the help()
function, as shown in the following example:
>>> help(deployer.hypervisors)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Hypervisor object
A hypervisor object represents a particular hypervisor defined in IBM Cloud
Orchestrator. Use the hypervisor object to query and manipulate the hypervisor
definition in the product. Attributes of the hypervisor object are represented as
Jython attributes on the hypervisor object. Relationships between the hypervisor
object and other resources on IBM Cloud Orchestrator are also represented as
Jython attributes on the hypervisor object. Manipulate these Jython attributes using
standard Jython mechanisms to change the corresponding data on IBM Cloud
Orchestrator.
You can work with hypervisors on the command line and help is available. To get
help for the hypervisors object, pass it as an argument to the help() function, as
shown in the following example:
>>> help(deployer.hypervisors)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Hypervisor attributes
Hhypervisors are automatically added as part of the discovery process for the
cloud group that represents their hypervisor manager. Hypervisor objects provide
the following attributes to work with them:
address
The host name or IP address (dotted decimal notation) at which the
hypervisor can be reached.
created
The creation time of the hypervisor, as number of seconds since midnight,
January 1, 1970 UTC. When the hypervisor is displayed, this value is
shown as the date and time in the local time zone. This field is read-only.
currentmessage
The message associated with the status of the hypervisor. It might, for
example, provide details about a problem if the hypervisor has been placed
in an error state. This field is read-only.
currentmessage_text
A textual description of the currentmessage value. Provides additional
status or details about what is happening or has happened to the
hypervisor resource. This field is read-only.
currentstatus
The status of the hypervisor. This field is read-only.
currentstatus_text
A textual description of the currentstatus value. This field is read-only.

Chapter 11. Reference

759

desiredstatus
Indicates the status in which you want the hypervisor. Setting this value
causes IBM Cloud Orchestrator to initiate the necessary steps to get the
hypervisor to this state.
desiredstatus_text
A textual description of the desiredstatus value. This field is read-only.
endpointtype
Specifies the type of endpoint type of this hypervisor object. This read-only
value is determined based on the actual endpoint type of the resource. The
value of the endpoint type can be one of the following:
v Hypervisor: The resource is a hypervisor.
v Pool: The resource is a pool.
v Cluster: The resource is a cluster.
id

The ID of the hypervisor. This field is read-only.

name

The name associated with this hypervisor. Each hypervisor must have a
unique name.

pvuscore
The processor value unit (PVU) score for the hypervisor. This attribute
includes the following information about the processor type:
v Vendor who created it (for example Intel)
v Brand (for example Xeon)
v Number of cores per chip (for example dual core or quad core)
This information can be derived from the PVU-table.xml file or entered
manually.
type

The type of this hypervisor. Valid value is OpenStack.

updated
The time the hypervisor was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the hypervisor is displayed, this
value is shown as the date and time in the local time zone. This field is
read-only.
UUID

The universally unique identifier for the hypervisor. For hypervisors that
do not have a UUID, this value will be "none".

version
The type and version of the server, as shown below:
v VMware ESX Server 4.0.0
virtualmachines
A list of virtual machines currently defined on this hypervisor.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Hypervisor methods
The following methods are provided for hypervisor objects:
discover()
Forces IBM Cloud Orchestrator to rediscover the network and storage to
which the hypervisor is attached. This method accepts a single optional

760

IBM Cloud Orchestrator 2.4.0.2: User's Guide

parameter that allows you to specify to opt-in or opt-out the discovered

network and storage. The following values are valid for this parameter:
T

Opt-in discovered network and storage

Opt-out discovered network and storage

The default is to opt-in the discovered network and storage.

isMaintenance()
Indicates if the hypervisor is in maintenance mode.
isNetworkInUse
Indicates if a network is used by the hypervisor.
isStorageInUse
Indicates if a storage resource is used by the hypervisor.
isQuiesced
Indicates if the hypervisor has been quiesced.
isStarted()
Indicates if the hypervisor is ready for use by IBM Cloud Orchestrator.
maintenance()
Places the hypervisor in maintenance mode.
quiesce
Quiesces the hypervisor so that it can not be used for new deployments.
setNetworkInUse
Set the inuse status of a network. Valid values are 'T' or 'F'
start() Places the hypervisor in a state in which it can be used by IBM Cloud
Orchestrator.

Starting the hypervisor

To start the hypervisor, use the start method on the hypervisor resource.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related information:
Jython
Python documentation

Chapter 11. Reference

761

Image command-line interface reference

You can work with images using the command-line reference.
For information about working with the command-line interface, see Using the
command-line interface on page 735.

Images object
An images object represents a collection of images in the catalog.
To get help for the images object, pass it as an argument to the help() function, as
shown in the following example:
>>> help(deployer.images)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Images methods
The following methods are provided for images objects:
get()

Get an image by the image ID. It accepts a single parameter: the image ID.

getOVF()
Get the OVF of an image. It accepts a single parameter: the image ID.
Image object
An Image object represents a particular image in the catalog. To get help
for the image object on the command-line interface, pass it as an argument
to the help() function, as shown in the following example:
>>> help(deployer.image)

Image object
Animage represents a particular image in the catalog.
To get help for the image object, pass it as an argument to the help() function, as
shown in the following example:
>>> help(deployer.image)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Image attributes
Image objects provide the following attributes to work with them:
architecture
The architecture of the image.
cloud

A reference to the cloud to which this virtual machine belongs. For more
information on the properties and methods supported by Cloud objects,
enter:
>>> help(deployer.cloud)

description
The description of the image.

762

IBM Cloud Orchestrator 2.4.0.2: User's Guide

hypervisor
The hypervisor of the image.
The image ID.

id

linked The linked status of the image. Must be True or False.

name

The image name.

repository
The repository the image is located in.
version
The version of the image.

Image methods
The following methods are provided for image objects:
link()

Link the image from the cloud group.

Installation Manager repository command-line interface reference

You can work with the internal Installation Manager repository by using the
IMRepository and IMRepositories objects on the IBM Cloud Orchestrator
command-line interface.

IMRepository object
An IMRepository object represents an IBM Installation Manager repository. Use the
IMRepository object to manage the IBM Installation Manager repository definition.
To get help for the IMRepository object on the command-line interface, pass it as
an argument to the help() function, as shown in the following example:
>>> help(deployer.imrepository)

IMRepositories object
An IMRepositories object represents a the collection of IBM Installation Manager
repositories.
To get help for the IMRepositories object on the command-line interface, pass it as
an argument to the help() function, as shown in the following example:
>>> help(deployer.imrepositories)

IMRepository attributes
categoryname
Category name for the IBM Installation Manager repository.
packageidversion
The ID and version for a software package.

IMRepositories methods
createCategory(<category name>)
Create the specified category in the Installation Manager repository.
>>> deployer.imrepositories.createCategory(Test)

deleteCategory(<category name>)
Delete the specified category in the Installation Manager repository.
Chapter 11. Reference

763

>>> deployer.imrepositories.deleteCategory(Test)

listCategory()
List the category names.
>>>deployer.imrepositories.listCategory()

uploadPackageFromLocal(<category name>, file)

Upload a software package from a local directory to the Installation Manager
repository.
>>>deployer.imrepositories.uploadPackageFromLocal(Test,
C:\\Download\\bpm\\8.5.0.0-WS-BPM-IFJR48757.zip)

listPackage()
List the software packages that are in the Installation Manager repository.
>>>deployer.imrepositories.listPackage()

deletePackage(<category name>, <package id>)

Delete the specified software package from the Installation Manager repository.
>>>deployer.imrepositories.deletePackage(Test,8.5.0.0-WS-BPMPCPD-IFPD48757_8.5.0.20131212_1929)

IP command-line interface reference

You can work with IP addresses, using the IPs and IP objects on the IBM Cloud
Orchestrator command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 735.

IPs object
An IPs object represents the collection of IP addresses defined within a particular
IP group. Objects of this type are accessed using the ips attribute of the IP group in
which they are contained, as shown in the following example:
>>> myipgroup = deployer.ipgroups[my ip group name][0]
>>> myipgroup.ips

Objects of this type are used to create, delete, iterate over, list and search for IP
addresses in IBM Cloud Orchestrator. Unlike other types of resource collections, IP
addresses have no name attribute. When searching for IP addresses within this
collection, matching is done against the ipaddress attribute.
When you are creating IPs objects, pass the IP address as a string in dotted
decimal notation to the create() method. To create multiple IPs objects, pass a list
of these strings, as shown in the following example:
>>> myipgroup.ips.create("1.2.3.4")
>>> myipgroup.ips.create(["1.2.3.5", "1.2.3.6"])

Note: Because IPs objects do not have a name property, the search string supplied
in any search operations is matched against the IP address.
You can work with IP addresses on the command line and help is available. To get
help for the IPs object, pass it as an argument to the help() function, as shown in
the following example:
>>> help(deployer.ips)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

764

IBM Cloud Orchestrator 2.4.0.2: User's Guide

IP object
An IP object represents a particular IP address defined in IBM Cloud Orchestrator.
Use the IP object to query and manipulate the IP address definition in the product.
Attributes of the IP address and relationships between the IP address and other
resources in IBM Cloud Orchestrator are represented as Jython attributes on the IP
object. Manipulate these Jython attributes using standard Jython mechanisms to
change the corresponding data in IBM Cloud Orchestrator.
IP objects are contained in the IPGroup object.
You can work with IP addresses on the command line and help is available. To get
help for the IP object, pass it as an argument to the help() function, as shown in
the following example:
>>> help(deployer.ip)

IP attributes
Unlike other types of resource collections, IP addresses have no name attribute.
When searching for IP addresses within this collection, matching is done against
the IPaddress attribute. The IP object has the following attributes:
created
The creation time of the IP, as number of seconds since midnight, January
1, 1970 UTC. When the IP is displayed, this value is shown as the date and
time in the local time zone. This field is read-only.
currentmessage
The message associated with the status of the IP. This field is read-only.
currentmessage_text
The message text describing the current message of the IP address. This
field is read-only.
currentstatus
The status of the IP. This field is read-only.
currentstatus_text
The message text describing the status of the IP address. This field is
read-only.
id

The ID of the IP. This field is read-only.

ipaddress
The IP address associated with this IP. The IP address must be unique and
must belong to the IP group under which this IP is defined. This field is
read-only.
ipgroup
A reference to the IPgroup object that contains this IP address. For more
information about the properties and methods supported by IPgroup
objects, enter the following command:
>>> help(deployer.ipgroup)

updated
The time the IP was last updated, as number of seconds since midnight,
January 1, 1970 UTC. When the IP is displayed, this value is shown as the
date and time in the local time zone. This field is read-only.
userhostname
The hostname that was entered that is associated with this IP.
Chapter 11. Reference

765

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

IP method
The IP object has the following method associated with it:
reset

Changes the IP status from Active to Inactive as shown in the following

example:
myip.reset()

CAUTION:
Use this method only when an IP object gets into an error state. Use this
method if an IP status is active in IBM Cloud Orchestrator, but the IP is
not active because a virtual machine has been deleted.

IPs object methods

The IPs object has the following methods:
create The create method for the IPs object is unique because it accepts different
parameters. The create(other) method defines a new IP address within an
IP group to the IBM Cloud Orchestrator. The single parameter to this
method can be any of the following values:
v A string containing the IP address in dotted decimal notation, 192.168.1.2
for example.
Note: The IP address must be within the subnet defined for the IP
group.
v As the name of a file containing a Jython expression that evaluates to
one of the values in this list.
v The deployer.wizard value or a wizard instance created by calling
deployer.wizard(). If either of these values is supplied, the
command-line interface prompts interactively for the values to create the
resource. IP objects must be created within the context of an IPGroup
object.
>>> myipgroup.ips.create(deployer.wizard)

See Wizard objects on the command-line interface on page 860 for

more information about using the wizard to create an IP object.
v A list of any of these values.
This method returns either an IPs object or a list of IPs objects, depending
on the parameter passed.
delete Deletes a resource in this collection. All information about this resource is
deleted from the IBM Cloud Orchestrator. The resource to be deleted can
be specified in any of the following ways:
v As an int or long that specifies the id of the resource to be deleted, as
shown in the following example:
>>> deployer.patterns.delete(17)

v As the resource object representing the resource to be deleted, as shown

in the following example:
>>> mypattern = deployer.patterns[4]
>>> deployer.patterns.delete(mypattern)

v As a list of any of these to delete multiple resources.

766

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This method raises exceptions to indicate problems deleting resources.

There is no return value.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related information:
Jython
Python documentation

IP group command-line interface reference

You can work with IP groups on the IBM Cloud Orchestrator command-line
interface using the IPgroups and IPgroup objects and attributes.
For general information about working with the command-line interface, see
Using the command-line interface on page 735.

IPgroups object
An IPgroups object represents the collection of IP groups defined to the IBM Cloud
Orchestrator. Objects of this type are used to create, delete, iterate over, list and
search for IP groups on the IBM Cloud Orchestrator.
IPgroups objects contain IPs objects and IPgroups objects have many networks.
You can work with the IPgroups object on the command line and help is available.
To get help for the IPgroups object, pass it as an argument to the help() function,
as shown in the following example:
>>> help(deployer.ipgroups)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

IPgroup object
An IPgroup object represents a particular IP group defined in IBM Cloud
Orchestrator. Use the IPgroup object to query and manipulate the IP group
definition in the product. Attributes of the IP group are represented as Jython
attributes on the IPgroup object. Relationships between the IP group and other
resources on the IBM Cloud Orchestrator are also represented as Jython attributes
on the IPgroup object. Manipulate these Jython attributes using standard Jython
mechanisms to change the corresponding data on the IBM Cloud Orchestrator.
You can work with the IPgroup object on the command line and help is available.
To get help for the IPgroup object, pass it as an argument to the help() function, as
shown in the following example:
>>> help(deployer.ipgroup)

IPgroup attributes
When you are creating an IP group, you must provide values for the following
attributes:
Chapter 11. Reference

767

v subnetaddress
v netmask
v primarydns
You can also provide values for the following attributes:
v name
v gateway
v secondarydns
The IPgroup object has the following attributes:
alternategateway
(Optional) The alternate gateway IP address to use for the IP group
networking.
computernameprefix
(Optional) If specified, it defines the prefix to use for the computer name.
created
The creation time of the IP group, as number of seconds since midnight,
January 1, 1970 UTC. When the IP group is displayed, this value is shown
as the date and time in the local time zone. This field is read-only.
description
(Optional) A basic description of the IP Group. This can be used to provide
more details about the usage or purpose of an IP group.
domain (Optional) The domain name to use for the IP Group network.
domainsuffixes
(Optional) A comma-separated list of domain suffixes that must be added
to the network settings of the virtual machine. For example, ibm.com or
us.ibm.com.
gateway
The default gateway associated with the IP group represented as a string
in dotted decimal notation, for example: 192.168.98.1.
hostnameprefix
(Optional) If specified, it is used as the hostname's prefix in the generated
virtual machine hostname.
id

The ID of the IP group. This field is read-only.

ips

The set of IP addresses defined within this IP group for use on virtual
machines. For more information about the properties and methods
supported by IPs objects, enter the following command:
>>> help(deployer.ips)

name

The display name associated with this IP group. If the name is not
specified, it defaults to the subnet address.

netmask
The network mask associated with the subnet address of the IP group that
is represented as a string in dotted decimal notation, for example:
255.255.255.0.
networks
The hypervisor network attachments associated with this IP group.

768

IBM Cloud Orchestrator 2.4.0.2: User's Guide

primarydns
The primary domain name system (DNS) server used for the IP group
represented as a string in dotted decimal notation, for example:
192.168.98.2.
primarywins
(Optional) The primary WINs address to use for the virtual machine. Only
used for Windows based deployments.
protocol
Specifies the protocol to be used for the IP Group network and can either
be dhcp or static. If dhcp, then all of the IP address based networking
properties are optional the deployments are done using this IP Group is set
up using DHCP.
secondarydns
The secondary DNS server used for the IP group represented as a string in
dotted decimal notation, for example: 192.168.98.3.
secondarywins
(Optional) The secondary WINs address to use for the virtual machine.
Only used for Windows based deployments.
updated
The time the IP group was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the IP group is displayed, this value
is shown as the date and time in the local time zone. This field is
read-only.
version
The version of the IP addresses for the IP group. The valid value is IPv4 or
IPv6.
Attention: Workloads that require IP caching must be deployed to cloud
groups with only IPv4 IP groups.
workgroup
(Optional) The Windows workgroup name to use for the virtual machine.
Only used for Windows based deployments.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related information:
Jython
Python documentation

Chapter 11. Reference

769

Mail delivery command-line interface reference

You can administer the mail delivery settings of IBM Cloud Orchestrator using the
command-line interface.

MailDelivery object
Namespace for mail settings. The MailDelivery object has the following attributes:
replytoaddress
Reply-to address (set to "" to use system administrator address)
smtpserver
The SMTP server used by IBM Cloud Orchestrator to send email. The
value is a string containing the host name or IP address of the SMTP
server. IP addresses must be specified in dotted decimal notation.
Related tasks:
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related information:
Jython
Python documentation

Network command-line interface reference

You can work with the network resource objects on the IBM Cloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.

Networks object
A networks object represents the collection of networks defined to IBM Cloud
Orchestrator. Objects of this type are used to delete, iterate over, list and search for
networks on IBM Cloud Orchestrator.
Note: Networks objects are automatically created by IBM Cloud Orchestrator and
cannot be manually defined.
You can work with networks objects on the command line and help is available. To
get help for the networks object, pass it as an argument to the help() function, as
shown in the following example:
>>> help(deployer.networks)

For more information about working with resource objects, see the Resources,
resource collections, and methods on page 842 section.

Network object
A network object represents a particular network defined in IBM Cloud
Orchestrator. Use the network object to query and manipulate the network
definition in the product. Attributes of the network object are represented as Jython
attributes on the network object. Relationships between the network object and
other resources on IBM Cloud Orchestrator are also represented as Jython

770

IBM Cloud Orchestrator 2.4.0.2: User's Guide

attributes on the network object. Manipulate these Jython attributes using standard
Jython mechanisms to change the corresponding data on the IBM Cloud
Orchestrator.
Network objects belong to hypervisors and IP groups.
You can work with network objects on the command line and help is available. To
get help for the network object, pass it as an argument to the help() function, as
shown in the following example:
>>> help(deployer.network)

Network attributes
The network object has the following attributes:
created
The creation time of the network, as number of seconds since midnight,
January 1, 1970 UTC. When the network is shown, this value is shown as
the date and time in the local time zone. This field is read-only.
currentmessage
The message associated with the status of the network. This field is
read-only.
currentmessage_text
The message text describing the status of the network. This field is
read-only.
currentstatus
The status of the network. This field is read-only.
currentstatus_text
The text describing the status of the network. This field is read-only.
hypervisor
A reference to the hypervisor that owns this network connection. For more
information about the properties and methods supported by hypervisor
objects, enter the following command:
>>> help(deployer.hypervisor)

id

The ID of the network. This field is read-only.

ipgroup
A reference to the IPGroup object to which this network is attached. For
more information about the properties and methods supported by IPGroup
objects, enter the following command:
>>> help(deployer.ipgroup)

name

The name associated with this network. Each network must have a unique
name.

updated
The time the network was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the network is displayed, this value
is shown as the date and time in the local time zone. This field is
read-only.
Specifies the virtual local area network (VLAN) associated with this
network. This value must be an integer value in the 0 - 4095 range,
inclusive.
Related information:
vlan

Chapter 11. Reference

771

Jython
Python documentation

Pattern type command-line interface

You can administer pattern types using the IBM Cloud Orchestrator command-line
interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.

PatternType object
A PatternType object represents a particular pattern type defined on IBM Cloud
Orchestrator. Use the PatternType object to query and manipulate the pattern type
definition. Attributes of the pattern type and relationships between the pattern
type and other resources on IBM Cloud Orchestrator are represented as Jython
attributes on the PatternType object. Manipulate these Jython attributes using
standard Jython mechanisms to make changes to the corresponding data on IBM
Cloud Orchestrator. To get help for the PatternType object, pass it as an argument
to the help() function, as shown in the following example:
>>> help(deployer.patterntype)

PatternTypes object
A PatternTypes object represents the collection of pattern types defined to IBM
Cloud Orchestrator. Objects of this type are used to create, delete, iterate over, list
and search for pattern types on IBM Cloud Orchestrator. To get help for the
PatternTypes object, pass it as an argument to the help() function, as shown in the
following example:
>>> help(deployer.patterntypes)

PatternType attributes
The PatternType object has the following attributes:
shortname
The short name of the pattern type.
name

The name of the pattern type.

version
The version of the pattern type.
description
The description of the pattern type.
status The status of the pattern type.
required
The prerequisites of the pattern type.

PatternType methods
The PatternTypes and PatternType objects have the following methods:
acceptLicense
Accept the license of a given pattern type.
deployer.patterntypes.get(<shortname>, <version>).acceptLicense()

772

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The version must be in vrmf format.

For example,>>>
deployer.patterntypes.get(webapp,2.0.0.1).acceptLicense()
list
List all pattern types. You can use deployer.patterntypes or
deployer.patterntypes.list.
For example, >>>deployer.patterntypes
By default, it will return pattern type with vr format, for example, webapp
2.0. You can use deployer.patterntypes.list({"version":"vrmf"}) to list
vrmf format, for example, webapp 2.0.0.1.
For example, >>>deployer.patterntypes.list({"version":"vrmf"})
get

Get a pattern type with short name and version.

deployer.patterntypes.get(<shortname>, <version> )

For example, >>> deployer.patterntypes.get(webapp,2.0.0.1)

create
Create a pattern type from a tgz file.
deployer.patterntypes.create(<tgz_file_path>).

For example, >>> deployer.patterntypes.create(E:\\dbaas2.0.0.1.tgz)

delete
Delete a pattern type.
deployer.patterntypes.delete(<shortname>, <version>)

The version must be in vrmf format.

For example, >>> deployer.patterntypes.delete(dbaas,2.0.0.1)
enable
Enable a pattern type.
deployer.patterntypes.get(<shortname>, <version>).enable()

The version must be in vrmf format.

For example, >>>
deployer.patterntypes.get(dbaas,2.0.0.1).enable()
disable
Disable a pattern type.
deployer.patterntypes.get(<shortname>, <version>).disable()

The version must be in vrmf format.

For example, >>>
deployer.patterntypes.get(dbaas,2.0.0.1).disable()

Chapter 11. Reference

773

Plug-in command-line interface reference

You can administer plug-ins in the catalog using the command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.

Plugin object
A Plugin object represents a particular plug-in defined in IBM Cloud Orchestrator.
Use the Plugin object to query and manipulate the plug-in definition. Attributes of
the plug-in and relationships between the plug-in and other resources in IBM
Cloud Orchestrator are represented as Jython attributes on the plug-in object.
Manipulate these Jython attributes using standard Jython mechanisms to make
changes to the corresponding data on the product.
To get help for the Plugin object, pass it as an argument to the help() function, as
shown in the following example:
>>> help(deployer.plugin)

Plugin attributes
The Plugin object has the following attributes:
create_time
The creation time of the plug-in.
creator
Creator of the plug-in.
description
The description of the plug-in.
last_modified
Time the plug-in was updated.
last_modifier
The last user who updated the plug-in.
name

The name of the plug-in.

Plugin methods
The Plugin object has the following methods:
list
List all plug-ins
deployer.plugins

or
deployer.plugins.list

Get a single plug-in by index

deployer.plugins[<index>]

For example, >>>deployer.plugins[0]

get
Get a single plug-in by plug-in name:
deployer.plugins.get(<plugin name>)

774

IBM Cloud Orchestrator 2.4.0.2: User's Guide

For example, >>>deployer.plugins.get("osgiebaosgirepo/1.0.0.0")

create
Create a plug-in
deployer.plugins.create(<file local path>)

For example, >>> deployer.plugins.create("C:\\testplugin1.0.0.0.tgz")

delete
Delete a plug-in
deployer.plugins.delete(<plugin_name>)

For example, >>> deployer.plugins.delete("firewall")

Problem determination command-line interface reference

You can work with IBM Cloud Orchestrator problem determination using the
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.

Diagnostics object
Returns the Diagnostics object representing the diagnostics package for the IBM
Cloud Orchestrator.
Help is available on the command-line interface for the Diagnostics object. To get
help, pass the Diagnostics object as an argument to the help() function, as shown
in the following example:
>>> help(deployer.diagnostics)

The Diagnostics object has one method, the get method. The get method
downloads the diagnostics package as a compressed file. This method takes an
optional path where the file is stored; the default path is ./trace.zip, as shown in
the following examples:
>>> deployer.diagnostics.get()
>>> deployer.diagnostics.get(/some/path/diagnostics.zip)

Trace object
The Trace object returns a TraceFile object representing the running trace file on
the IBM Cloud Orchestrator.
Help is available for the Trace object on the command-line interface. To get help,
pass the Trace object as an argument to the help() function, as shown in the
following example:
>>> help(deployer.trace)

Trace methods
The Trace object has the following methods:
add

Adds a logger and optional log level to the trace file specification. Logger
names use Java package name syntax and log levels are one of the
following values:
Chapter 11. Reference

775

v
v
v
v
v

OFF
SEVERE
WARNING
CONFIG
INFO

v FINE
v FINER
v FINEST
The default value is OFF. The add method is shown in the following
examples:
>>> deployer.trace.add(com.ibm.ws.deployer, FINE)
>>> deployer.trace.add(com.ibm.ws.deployer.not.interested)

remove
Removes an existing logger from the trace file specification. Logger names
use Java package name syntax, as shown in the following example:
>>> deployer.trace.remove(com.ibm.ws.deployer.not.interested)

set

Sets the log level for an existing logger in the trace file specification.
Logger names use Java package name syntax and log levels are one of the
following values:
v OFF
v SEVERE
v WARNING
v CONFIG
v INFO
v FINE
v FINER
v FINEST
The set method is shown in the following examples:
>>> deployer.trace.set(com.ibm.ws.deployer, FINE)
>>> deployer.trace.set(com.ibm.ws.deployer, SEVERE)

spec

Returns a map with the trace file specification for the IBM Cloud
Orchestrator. The map has key-value pairs in which the key is the package
name and the value is the log level.

tail

Prints the last <n> lines of the file, where <n> is an integer, as shown in
the following example:
>>> deployer.trace.tail()
>>> deployer.errors.tail(100)

The default value is 10 (ten).

Errors object
The Errors object returns an ErrorFile object representing the running error file
on the IBM Cloud Orchestrator.
Help is available for the Errors object on the command-line interface. To get help,
pass the Errors object as an argument to the help() function, as shown in the
following example:

776

IBM Cloud Orchestrator 2.4.0.2: User's Guide

>>> help(deployer.errors)

The Errors object has one method, the tail method. The tail method prints the last
<n> lines of the file, in which <n> is an integer. The tail method is shown in the
following example:
>>> deployer.trace.tail()
>>> deployer.errors.tail(100)

The default value is 10 (ten).

For more information about the command-line interface tool, see the Using the
command-line interface on page 735 section. For more information about working
with resources on the command-line interface, see the Resource collections on the
command line on page 847 section.
Related tasks:
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related information:
Jython
Python documentation

Script package command-line interface reference

You can administer script packages using the IBM Cloud Orchestrator
command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.

Scripts object
A Scripts object represents the collection of script packages defined to IBM Cloud
Orchestrator. Objects of this type are used to create, delete, iterate over, list and
search for script packages on the IBM Cloud Orchestrator.
Help is available for the Scripts object on the command-line interface. To get help,
pass the Scripts object as an argument to the help() function, as shown in the
following example:
>>> help(deployer.scripts)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.

Script object
A Script object represents a particular script defined in IBM Cloud Orchestrator.
Use the Script object to query and manipulate the script definition in the product.
Attributes of the script and relationships between the script and other resources in
IBM Cloud Orchestrator are represented as Jython attributes on the Script object.
Manipulate these Jython attributes using standard Jython mechanisms to change
the corresponding data in IBM Cloud Orchestrator.

Chapter 11. Reference

777

Help is available for the Script object on the command-line interface. To get help,
pass the Script object as an argument to the help() function, as shown in the
following example:
>>> help(deployer.script)

Script attributes
The pattern Script object has the following attributes:
acl

The access control list for this script. This field is read-only. For additional
help about using this object, see ACL object on page 862 or enter the
following command:
>>> help(deployer.acl)

archive
The script archive object associated with this script. For more information,
see Script.Archive object on page 780. This field is read-only.
command
The command to be run for this script package. This field contains a string
value with a maximum of 4098 characters.
commandargs
The arguments passed to the command. This field contains a string value
with a maximum of 4098 characters.
created
The creation time of the script, as number of seconds since midnight,
January 1, 1970 UTC. When the script is displayed, this value is shown as
the date and time in the local timezone. This field is read-only.
currentstatus
The status of the script package. This field contains an eight character
string value that is generated by the product.
currentstatus_text
A textual representation of currentstatus in the preferred language of the
requester. This string is automatically generated by the product. This field
is read-only.
description
The description of the script package. This field contains a string value
with a maximum of 1024 characters.
environment
Manages the key/value pairs that define the environment, or parameters,
of the script. The environment property holds the script keys and default
values for the script package. It is used such as a Jython dict object, as
shown in the following example:
>>> myscript.environment
{
"scriptkey1": "value for scriptkey1",
"scriptkey2": "value for scriptkey2"
}
>>> myscript.environment[scriptkey1]
value for scriptkey1
>>> myscript.environment[foo] = bar
>>> myscript.environment
{
"foo": "bar",
"scriptkey1": "value for scriptkey1",
"scriptkey2": "value for scriptkey2"

778

IBM Cloud Orchestrator 2.4.0.2: User's Guide

}
>>> del myscript.environment[foo]
>>> myscript.environment
{
"scriptkey1": "value for scriptkey1",
"scriptkey2": "value for scriptkey2"
}

This attribute is read-only.

execmode
This attribute specifies when the script package is run on the virtual
machine. The following values can be used for this attribute:
deployer.script.VIRTUAL_SYSTEM_CREATION_EXECMODE
This value specifies that the script is run when the virtual system
instance is created.
deployer.script.VIRTUAL_SYSTEM_DELETION_EXECMODE
This value specifies that the script is run when the virtual system
instance is deleted.
deployer.script.USER_INITIATED_EXECMODE
This value specifies that the script is run when requested by the
user. The script can be run an unlimited number of times on a
virtual machine.
id

The ID of the script. The value of this attribute is an integer and is

read-only.

label

The label for the script.

location
The directory, on the virtual machine, into which files for this script
package are to be placed. This field contains a string value with a
maximum of 4098 characters.
log

The directory on the virtual machine to hold the log files generated by this
script package. This field contains a string value with a maximum of 4098
characters.

name

The name associated with this script. Each script must have a unique
name. This field contains a string value with a maximum of 1024
characters.

owner

A user object that references the owner of this script package. For more
information about the properties and methods supported by user objects,
enter the following command:
>>> help(deployer.user)

ostype The operating system where the script package can run. Specify one of the
following values:
linux/unix
Specifies the script package is applicable to Linux or Unix systems.
windows
Specifies the script package is applicable to Windows systems.
both

Specifies the script package is applicable to both Linux/Unix and

Windows systems.

empty string ("")

Defaults to the linux/unix value.
Chapter 11. Reference

779

timeout
The maximum amount of time to wait for this script package to finish
running on the virtual machine. Specify the timeout, as the number of
milliseconds to wait, or 0 (zero) to wait indefinitely for the script package
to complete. The value of this attribute is an integer.
updated
The time the script was last updated, as number of seconds since midnight,
January 1, 1970 UTC. When the script is displayed, this value is shown as
the date and time in the local timezone. This field is read-only.

Script methods
The Script object attributes have the following methods:
clone

Creates a copy of this script package with all the same files, fields, and
settings. The name of the new script is provided and the acl attribute is
empty.

isDraft
Indicates if this script is in draft mode.
isReadOnly
Indicates if this script is read-only.
makeReadOnly
Makes this script read-only. When the script is made read-only, the script
cannot be modified.

Script.Archive object
A Script.Archive object represents the archive file associated with a particular
script in IBM Cloud Orchestrator. This object provides mechanisms to query and
manipulate the script archive in the product.

Script.Archive methods
The Script.Archive object has the following methods:
get

This method retrieves the archive currently associated with the script. This
method has one required parameter that indicates where the script archive
is to be saved. It can be either of the following values:
v A string containing the name of a file in which to save the archive. If the
file name does not end in .zip, .zip is automatically appended to the
file name.
v A Jython file object, as shown in the following example:
>>> myscript.archive.get(/path/to/foo.zip)

You must ensure that the file object can correctly handle binary data.
The script archive is returned in a compressed (.zip) file format.
__lshift__
This method is started implicitly when the Archive object is used as the
left argument of a left shift operator ( << ). It calls the set() method with
the right argument of the operator. This method is shown in the following
example:
>>> myscript.archive << /path/to/file

780

IBM Cloud Orchestrator 2.4.0.2: User's Guide

__rshift__
This method is started implicitly when the Archive object is used as the
left argument of a right shift operator ( >> ). It calls the get() method with
the right argument of the operator. This method is shown in the following
example:
>>> myscript.archive >> /path/to/file.zip

set

This method sets the archive associated with the script. It has one required
parameter that indicates the source of the script archive to be uploaded. It
can be either of the following values:
v A string containing the name of a file from which to get the archive.
v A Jython file object.
Ensure that the file object can correctly handle binary data. This method is
shown in the following example:
>>> myscript.archive.set(/path/to/foo)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
You can control the user access to scripts with the ACL object. For more information
about the ACL object, see the ACL object on page 862 topic.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related reference:
ACL object on page 862
You can use the access control list (ACL) object to set and control user access for
other IBM Cloud Orchestrator resources.
Related information:
Jython
Python documentation

Snapshots on the command-line interface

You can administer snapshots of virtual system instances by using the IBM Cloud
Orchestrator command-line interface.
For general information about working with the command-line interface, see the
Using the command-line interface on page 735 section.

Snapshots object
A Snapshots object represents the collection of snapshots taken for a particular
virtual system instance. Objects of this type are accessed using the snapshots
property of the VirtualSystem object in which they are contained, as shown in the
following example:
>>> myvs = deployer.virtualsystems[my virtualsystem][0]
>>> myvs.snapshots

Objects of this type are used to create, delete, iterate over, list and search for
snapshots on the IBM Cloud Orchestrator
Chapter 11. Reference

781

Snapshots are created, as shown in the following example:

VirualSystem.createsnapshot()

The following example accesses snapshots:

VirtualSystem.snapshots

To get help on the command-line interface for the snapshots object, pass the name
of the object as an argument to the help() function. See the following example:
>>> help(deployer.snapshots)

Snapshot object
A Snapshot object represents a particular snapshot defined on the IBM Cloud
Orchestrator. Use the Snapshot object to query and manipulate the snapshot
definition in the product. Attributes of the Snapshot object are represented as
Jython attributes on the Snapshot object. Relationships between the Snapshot object
and other resources on the IBM Cloud Orchestrator are also represented as Jython
attributes on the Snapshot object. Manipulate these Jython attributes using
standard Jython mechanisms to change the corresponding data on the IBM Cloud
Orchestrator.
Help is available on the command-line interface for the Snapshot object. To get
help, pass the Snapshot object as an argument to the help() function, as shown in
the following example:
>>> help(deployer.snapshot)

The Snapshot object has the following method:

restore()
Restores this snapshot.
The Snapshot object has the following attribute:
virtualsystem
A VirtualSystem object that references the virtual system instance to which
this Snapshot object belongs. For more information about the properties
and methods supported by VirtualSystem objects, enter the following
command:
>>> help(deployer.virtualsystem)

For more information about the command-line interface, see the Using the
command-line interface on page 735 section. For more information about working
with resources on the command-line interface, see the Resources, resource
collections, and methods on page 842 section.
You can control user access to virtual system instances using the ACL object. For
more information about the ACL object, see the ACL object on page 862 topic.
Related tasks:
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related information:
Jython
Python documentation

782

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Storage command-line interface reference

You can administer storage resource objects using the IBM Cloud Orchestrator
command-line interface.
Note: Hypervisor storage cannot be manually defined to IBM Cloud Orchestrator.
Storage is automatically discovered when the hypervisor is defined.
For general information about working with the command-line interface, see the
Using the command-line interface on page 735 section.

Storages object
A storages object represents the collection of hypervisor storage defined to the
IBM Cloud Orchestrator. Objects of this type are used to delete, iterate over, list
and search for storage devices on IBM Cloud Orchestrator.
You can work with storage on the command line and help is available. To get help
for the storages object, pass it as an argument to the help() function, as shown in
the following example:
>>> help(deployer.storage)

Storage object
A storage object represents a particular storage defined in IBM Cloud Orchestrator.
Use the storage object to query and manipulate the storage definition on the
product. Attributes of the storage object are represented as Jython attributes on the
storage object. Relationships between the storage object and other resources in the
IBM Cloud Orchestrator are also represented as Jython attributes on the storage
object. Manipulate these Jython attributes using standard Jython mechanisms to
change the corresponding data in IBM Cloud Orchestrator.
You can work with storage on the command line and help is available. To get help
for the storage object, pass it as an argument to the help() function, as shown in
the following example:
>>> help(deployer.storage_)

Storage attributes
The storage object has the following attributes:
created
The creation time of the storage object, as number of seconds since
midnight, January 1, 1970 UTC. When the storage object is displayed, this
value is shown as the date and time in the local time zone. This field is
read-only.
hypervisors
The set of hypervisors that are attached to this storage.
hypervisorstorageid
The identifier used by hypervisors to identify this storage. It is
automatically determined so this field is read-only.
id

The ID of the storage object. This field is read-only.

name

The name associated with this storage object. Each storage object must
have a unique name.

Chapter 11. Reference

783

updated
The time the storage was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the storage is displayed, this value
is shown as the date and time in the local time zone. This field is
read-only.
Related information:
Jython
Python documentation

Virtual application instance command-line interface reference

You can administer virtual application instance using the IBM Cloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.

VirtualApplication object
A VirtualApplication object represents a particular virtual application instance
defined on IBM Cloud Orchestrator. Use the VirtualApplication object to query
and manipulate the virtual application instance definition. Attributes of the virtual
application instance and relationships between the virtual application instance and
other resources on IBM Cloud Orchestrator are represented as Jython attributes on
the VirtualApplication object. Manipulate these Jython attributes using standard
Jython mechanisms to make changes to the corresponding data on IBM Cloud
Orchestrator. To get help for the VirtualApplication object, pass it as an argument
to the help() function, as shown in the following example:
>>> help(deployer.virtualapplication)

VirtualApplications object
A VirtualApplications object represents the collection of virtual application
instances defined to IBM Cloud Orchestrator. Objects of this type are used to
create, delete, iterate over, list and search for virtual application instances on IBM
Cloud Orchestrator. To get help for the VirtualApplications object, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.virtualapplications)

VirtualApplication methods
The VirtualApplication and VirtualApplications object have the following
methods:
list
List all virtual application instances.
deployer.virtualapplications

or
deployer.virtualapplications.list

Search for virtual application instances with a filter (dict format):

deployer.virtualapplications.list(<filter in dict format>)

For example, >>>

deployer.virtualapplications.list({app_type:application})

784

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Get a single virtual application instance by index:

deployer.virtualapplications[<index>]

For example, >>>deployer.virtualapplications[0]

get
Get a single virtual application instance with depl_id.
deployer.virtualapplications.get(<depl_id>)

For example, >>> deployer.virtualapplications.get("d-15368912-20db4d65-958b-36f54fa1e462")

vminstances
Show VM instance details of a virtual application instance.
deployer.virtualapplications.vminstances(<depl_id>)

For example, >>> deployer.virtualapplications.get("d-2e0c8abb-373f46fc-a05f-a255af3d3120").vminstances

terminate
Terminate a virtual application instance.
deployer.virtualapplications.terminate(<depl_id>)

For example, >>> deployer.virtualapplications.terminate("d-0d1ede95f0cf-4d71-9b2e-ffa3bf80871c")

delete
Delete a virtual application instance.
deployer.virtualapplications.delete(<depl_id>)

For example, >>> deployer.virtualapplications.delete("d-0d1ede95f0cf-4d71-9b2e-ffa3bf80871c")

shareuser
Share a virtual application with another user.
deployer.virtualapplications.get(<depl_id>).shareuser(<username>,<access rights>)

For example, >>>deployer.virtualapplications.get("d-0d1ede95-f0cf4d71-9b2e-ffa3bf80871c").sharegroup("users","F")

sharegroup
Share a virtual application with another group.
deployer.virtualapplications.get(<depl_id>).sharegroup(<username>,<access rights>)

For example, >>>deployer.virtualapplications.get("d-0d1ede95-f0cf4d71-9b2e-ffa3bf80871c").sharegroup("users","F")

startvm
Start a virtual machine.
deployer.virtualapplications.get(<depl_id>)startvm(<node_id>)

For example, >>>deployer.virtualapplications.get(d-86148d3c-8e8542f0-b975-db75e84b1dd7).startvm(database-db2.11304523030092)

stopvm
Chapter 11. Reference

785

Stop a virtual machine.

deployer.virtualapplications.get(<depl_id>)startvm(<node_id>)

For example, >>>deployer.virtualapplications.get(d-86148d3c-8e8542f0-b975-db75e84b1dd7).stop(database-db2.11304523030092)

refresh
Refresh the cached attribute values.
deployer.virtualapplications.get(<depl_id>).refresh()

For example, >>>deployer.virtualapplications.get(d-12bbc2a0-9e6e453c-b6bc-fce578fc5873). refresh()

maintain
Put a virtual application instance in maintenance mode.
deployer.virtualapplications.get(<depl_id>).maintain()

For example, >>>deployer.virtualapplications.get(d-12bbc2a0-9e6e453c-b6bc-fce578fc5873). maintain()

resume
Resume a virtual application instance from maintenance mode.
deployer.virtualapplications.get(<depl_id>).resume()

For example, >>>deployer.virtualapplications.get(d-12bbc2a0-9e6e453c-b6bc-fce578fc5873). resume()

upgrade
Upgrade the pattern type of a virtual application instance to the latest.
deployer.virtualapplications.get(<depl_id>).upgrade()

For example, >>>deployer.virtualapplications.get(d-12bbc2a0-9e6e453c-b6bc-fce578fc5873). upgrade()

Virtual application pattern command-line interface reference

You can administer virtual application pattern using the IBM Cloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.

ApplicationPattern object
An ApplicationPattern object represents a particular virtual application pattern
defined on IBM Cloud Orchestrator. Use the ApplicationPattern object to query
and manipulate the virtual application pattern definition. Attributes of the virtual
application pattern and relationships between the virtual application pattern and
other resources on IBM Cloud Orchestrator are represented as Jython attributes on
the ApplicationPattern object. Manipulate these Jython attributes using standard
Jython mechanisms to make changes to the corresponding data on IBM Cloud
Orchestrator. To get help for the ApplicationPattern object, pass it as an argument
to the help() function, as shown in the following example:
>>> help(deployer.application)

786

IBM Cloud Orchestrator 2.4.0.2: User's Guide

ApplicationPatterns object
An ApplicationPatterns object represents the collection of virtual application
patterns defined to IBM Cloud Orchestrator. Objects of this type are used to create,
delete, iterate over, list and search for virtual application patterns on IBM Cloud
Orchestrator. To get help for the ApplicationPatterns object, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.applications)

ApplicationPattern attributes
The ApplicationPattern object has the following attributes:
acl

The access control list for this application pattern.

app_id The ID of the application pattern. The application pattern ID has to be

unique. This value is automatically generated and cannot be changed.
app_name
The name of the application pattern. The name of the application pattern
does not have to be unique.
app_type
Type of the application pattern.
artifacts
Artifacts of the application pattern.
create_time
The creation time of the application pattern.
creator
Creator of the application pattern.
description
The description of the application pattern.
last_modified
Time the application pattern was updated.
last_modifier
The last user who updated the application pattern.

ApplicationPattern methods
The ApplicationPattern and ApplicationPatterns object have the following
methods:
list

List all applications patterns.

deployer.applications

Get a single application pattern by index:

deployer.applications[<index>]

For example, >>> deployer.applications[0]

create
Create an application pattern:
deployer.applications.create(<specific attributes>)

Create an empty application pattern:

Chapter 11. Reference

787

deployer.applications.create("<local file path>")

Create an application pattern with JSON file or .zip file (the file type is
decided by the file extension). For example:
v Use specific attributes:
>>> deployer.applications.create({name:demoApp})

v Use .zip file or JSON file:

v >>> deployer.applications.create("C:\\sample.json")
delete
Delete an application pattern.
deployer.applications.delete(<app_ID>)

For example, >>> deployer.applications.delete("a-6aa5bf17-0c1e-457cb135-7c8d19401109")

update
Update an application pattern.
deployer.application.get(<app_ID>).update(<local file path>")

For example, >>> deployer.applications.get("a-514a4175-a771-4b3f8761-0227663d9181").update("C:\\sample.zip")

clone
Clone an application pattern from an existing application pattern.
deployer.application.get(<app_ID>).clone(<app_name>, <app_type>)

where app_type is an optional parameter. The default value is

"application".
For example, >>> deployer.applications.get("a-7dd50b00-c74c-4c63ab70-abd7dff7fcdf").clone("clonedTest")
deploy
Deploy an application pattern.
deployer.applcations.get(<app_ID>).deploy(<depl_name>,
<cloud object or env dict>, <certFile>, <params>)

The second parameter can be a Cloud object or a dictionary to describe the

environment profile. The environment dictionary format is:
{
environment_profile: <env_profile_obj> or <env_profile_id>
cloud_group: <cloud_group_obj> or <cloud_group_id>
ip_group: <ip_group_obj> or <ip_group_id>
ip_version: IPv4 or IPv6
}

You can use ssh-keygen to generate SSH keys and save the public key in a
file.
The <certFile> and <params> parameters are optional.
The format of <params> is:
{ node_link_id.attributeId: attributeValue, groups:{node_link_id.groupId: True/False} }.

You must specify groups if there is a group definition in the plug-in

metadata.

788

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Example:
sample=deployer.applications.get(a-b62aeddb-6b43-4421-a0b6-df41b44c5407)
env=deployer.environmentprofiles[0]
cloud = env.clouds.keys()[0]
ipgroup=env.clouds[cloud].ipgroups.keys()[0]
deployOptions = {"environment_profile" : env,
"cloud_group": cloud,
ip_group: ipgroup,
ip_version: IPv4
}
vapp = sample.deploy(env_test, deployOptions)

refresh
Call this method before getting status of the instance.
deployer.virtualapplications.get(<depl_id>).refresh()

For example, >>> deployer.virtualapplications.get(d-12bbc2a0-9e6e453-b6bc-fce578fc5873).refresh()

maintain
Put a virtual application instance in maintenance mode.
deployer.virtualapplications.get(<depl_id>).maintain()

For example, >>>>deployer.virtualapplications.get(d-12bbc2a0-9e6e453c-b6bc-fce578fc5873).maintain()

resume
Resume a virtual application instance from maintenance mode.
deployer.virtualapplications.get(<depl_id>).resume()

For example, deployer.virtualapplications.get(d-12bbc2a0-9e6e-453cb6bc-fce578fc5873).resume()

upgrade
Upgrade the pattern type of a virtual application instance to the latest.
deployer.virtualapplications.get(<depl_id>).upgrade()

For example, deployer.virtualapplications.get(d-12bbc2a0-9e6e-453cb6bc-fce578fc5873).upgrade()

monitoring
Get all monitoring data (both servers and roles) for the given virtual
application.
deployer.virtualapplications.get(<id>).monitoring

or
deployer.virtualapplications[<index>].monitoring

For example, deployer.virtualapplications[<index>].monitoring

Sample output:
>>> deployer.virtualapplications[0].monitoring
{
"roles": (nested object),
"servers": (nested object),
}

getMetrics
Chapter 11. Reference

789

Get the metrics data of a server.

deployer.virtualapplications[0].monitoring.servers[<index>].getMetrics(<metricType>)

Sample output:
>>>virtualapplication = deployer.virtualapplications[0]
>>>servers = virtualapplication.monitoring.servers
>>> servers[0].getMetrics()
{
"CPU": {
"IO_Wait": 0.75,
"Idle_CPU": 93.17,
"System_CPU": 3.69,
"Time_Stamp": 1302279676016,
"User_CPU": 2.39
},
"DISK": {
"Blocks_Reads_Per_Second": 0,
"Blocks_Written_Per_Second": 13867,
"Time_Stamp": 1302279676016
},
"MEMORY": {
"Memory_Cache": 571.7,
"Memory_Free": 33.38,
"Memory_Free_Percent": 2,
"Memory_Total": 2000.0,
"Memory_Used": 1966.61,
"Memory_Used_Percent": 98,
"Swap_Free_Percent": 100,
"Swap_Used_Percent": 0,
"Time_Stamp": 1302279676016
},
"NETWORK": {
"Bytes_Received_per_sec": 7402,
"Bytes_Transmitted_per_sec": 4172,
"Time_Stamp": 1302279676016
},
"PaaS": {
"Private_IP": "10.102.129.79",
"Time_Stamp": 1302279676016,
"availability": "NORMAL",
"deploymentId": "d-694ca59c-a212-4b32-b083-d860a871e7f2",
"serverName": "application-was.11302175160418",
"state": "RUNNING"
}
}

monitoring roles
Get monitoring metrics data of a role.
deployer.virtualapplications[0].monitoring.roles[<index>].getMetrics(<metricType>)

Sample output:
>>>virtualapplication = deployer.virtualapplications[0]
>>>roles= virtualapplication.monitoring.roles
>>> roles[0].getMetrics()
{
"PaaS": {
"Private_IP": "10.102.129.79",
"Time_Stamp": 1302279782294,
"availability": "UNKNOWN",
"deploymentId": "d-694ca59c-a212-4b32-b083-d860a871e7f2",
"roleName": "application-was.11302175160418.WAS",
"serverName": "application-was.11302175160418",
"state": "RUNNING"
},

790

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"WAS_JDBCConnectionPools": {
"MaxPercentUsed": 0,
"MaxWaitTime": 0,
"MinPercentUsed": 0,
"MinWaitTime": 0,
"PercentUsed": 0,
"Time_Stamp": 1302279782294,
"WaitTime": 0
},
"WAS_JVMRuntime": {
"HeapSize": 114055,
"JVMHeapUsed": 48,
"Time_Stamp": 1302279782294,
"UsedMemory": 55756
},
"WAS_TransactionManager": {
"ActiveCount": 0,
"CommittedCount": 150,
"RolledbackCount": 0,
"Time_Stamp": 1302279782294
},
"WAS_WebApplications": {
"MaxServiceTime": 0,
"MinServiceTime": 0,
"RequestCount": 0,
"ServiceTime": 0,
"Time_Stamp": 1302279782294
}
}

getLogs
List all logs that are available for downloading.
deployer.virtualapplications[<index>].vminstances().instances[<instance_index>].logging.getLogs()

Sample output:
>>> deployer.virtualapplications[0].vminstances().instances[0].logging.getLogs()
{DB2:[/home/db2inst1/sqllib/log/instance.log,
/home/db2inst1/sqllib/db2dump/stmmlog/stmm.0.log,
/home/db2inst1/sqllib/db2dump/db2inst1.nfy, /home/db2inst1/sqllib/db2dump/db2diag.log],
IWD Agent:
[/opt/IBM/maestro/agent/usr/servers/Database-db2.11319107992348/logs/Database-db2.11319107992348.DB2/trace.log,
/opt/IBM/maestro/agent/usr/servers/Database-db2.11319107992348/logs/Database-db2.11319107992348.DB2/console.log,
/opt/IBM/maestro/agent/usr/servers/Database-db2.11319107992348/logs/Database-db2.11319107992348.systemupdate/
console.log,
/0config/0config.log], OS: [/var/log/boot.log, /var/log/maillog, /var/log/messages,
/var/log/brcm-iscsi.log, /var/log/acpid, /var/log/wtmp, /var/log/yum.log, /var/log/mcelog,
/var/log/spooler, /var/log/dmesg, /var/log/secure, /var/log/cron, /var/log/rpmpkgs]}

download logs
deployer.virtualapplications[<index>].vminstances().instances[<instance_index>].logging.
download(<log file name>, <the local file path and file name to be saved>)

Sample output:
>>> deployer.virtualapplications[0].vminstances().instances[0].logging.download
("/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1/SystemOut.log", "E:/test.log")
>>>

Chapter 11. Reference

791

Virtual images command-line interface reference

You can manage virtual images in the catalog using the IBM Cloud Orchestrator
command-line interface. Virtual images provide the operating system and product
binary files to create a virtual system instance.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.

VirtualImages object
A VirtualImages object represents the collection of virtual images defined to IBM
Cloud Orchestrator. Objects of this type are used to create, delete, iterate over, list
and search for virtual images on the IBM Cloud Orchestrator.
You can work with virtual images on the command line and help is available. To
get help for the VirtualImages object, pass it as an argument to the help()
function, as shown in the following example:
>>> help(deployer.virtualimages)

VirtualImages attributes
progressIndicators
This boolean attribute specifies if a progress indicator displays when
uploading a virtual image from the command-line interface. The default
value of the progressIndicators attribute is false.

VirtualImages methods
The VirtualImages object has the methods described for a typical resource
collection. The following methods are unique to VirtualImages as their parameters
and return values differ from what is expected:
create Imports a new virtual image or images to the IBM Cloud Orchestrator. The
attributes to import the new virtual images can be specified in any of the
following ways:
v As a string specifying the URL from which the virtual image can be
downloaded, as shown in the following example:
>>> deployer.virtualimages.create
(http://server.xyz.com/path/to/foo.ova)

v As the name of a local virtual image open virtual appliance (OVA) file to
be uploaded to IBM Cloud Orchestrator, as shown in the following
example:
>>> deployer.virtualimages.create(/path/to/foo.ova)

Tip: Passing the OVA file to the product takes up more space on the
machine than specifying the URL of the OVA file. If space is an issue,
consider pointing to the OVA file with a string specifying the URL
instead.
v As a Jython file object that references the local OVA file, as shown in the
following example:
>>> deployer.virtualimages.create(open(/path/to/foo.ova, rb))

v As a dictionary (dict) object with the required keys, as shown in the

following example:
>>> deployer.virtualimages.create({url: http://... })

792

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v As the name of a file containing a Jython expression that evaluates to

one of the values in this list.
v As the value deployer.wizard or a wizard instance created by calling
deployer.wizard(). If either of these values is supplied, the
command-line interface prompts interactively for the values to create the
resource. For more information about using the wizard to create a
virtualimage object, see Wizard objects on the command-line interface
on page 860.
v As a list of any of these options, in which case multiple virtual images
are imported, as shown in the following example:
>>> deployer.hypervisors.create([/path/to/foo1.ova,
/path/too/foo2.ova])

This method returns a VirtualImage object for the newly created virtual
image, or a list of VirtualImage objects if multiple virtual images were
created. Because of their size, importing virtual images takes several
minutes. If the location of the OVA file was specified using a local file
name or file object, the OVA file is uploaded to the IBM Cloud
Orchestrator before this method returns. Otherwise, this method queues
the operation on the IBM Cloud Orchestrator and returns immediately. The
returned VirtualImage objects can be used to track the status of the import
process on the IBM Cloud Orchestrator.
import
The import method is an alias for the create() method and uses the same
parameters and return values.
link

Links one or more virtual images to the IBM Cloud Orchestrator image
catalog. This method accepts the following parameters:
v Cloud group ID as first attribute.
v One or more OpenStack virtual image IDs separated by a comma. To
identify the virtual image IDs, use the nova image-list command in
your OpenStack environment.
The following example shows the link method:
>>> deployer.virtualimages.link
(1, 2496c17c-c303-4dd1-9008-0d16f8161b9c,
fab6d6be-dc4f-4dbe-bd41-4c9abc42b13e,
0adaaaba-ce86-48bf-8d62-c28a0cb0ebb1)

For more information about working with resource objects, see the Resources,
resource collections, and methods on page 842 section.

VirtualImage object
A VirtualImage object represents a particular virtual image defined to IBM Cloud
Orchestrator. Use the VirtualImage object to query and manipulate the virtual
image definition in IBM Cloud Orchestrator. Attributes of the virtual image
resource and relationships between the virtual image and other resources in IBM
Cloud Orchestrator are represented as Jython attributes on the VirtualImage object.
Manipulate these Jython attributes using standard Jython mechanisms to change to
the corresponding data on the IBM Cloud Orchestrator.
You can work with a virtual image on the command line and help is available. To
get help for the VirtualImage object, pass it as an argument to the help() function,
as shown in the following example:
>>> help(deployer.virtualimage)
Chapter 11. Reference

793

VirtualImage attributes
The VirtualImage object has the following attributes, all which are read only:
acl

The access control list for this virtual image.

advancedoptionsaccepted
This attribute specifies if the virtual images advanced options are enabled.
The default value for this boolean attribute is false.
build

The build number of the virtual image, automatically determined. This

field contains a string value with a maximum of 1024 characters.

created
The creation time of the virtual image, as number of seconds since
midnight, January 1, 1970 UTC. When the virtual image displays, this
value is shown as the date and time in the local time zone.
currentmessage
The message associated with the status of the virtual image. This field
contains an eight character string value that is generated by the product.
currentmessage_text
This attribute is a string representation of currentmessage in the preferred
language of the requester. This attribute is automatically generated by the
product.
currentstatus
The status of the virtual image. This field contains an eight character string
value that is generated by the product.
currentstatus_text
This attribute is a string representation of currentstatus in the preferred
language of the requester. This attribute is automatically generated by the
product.
description
The description of the virtual image. This field contains a string value with
a maximum of 1024 characters.
hardware
The default hardware configuration for the virtual image.
id

The ID of the virtual image. This attribute is an integer value.

license
The license attribute contains complete information about the licenses
defined in the virtual image. A virtual image contains some number of
licenses organized into some number of collections. Exactly one license
from each collection must be accepted before the virtual image can be
used. The value of the licenses attribute is a Python dict object. Each key
in the dict object is the string ID of a collection of licenses. Each value is a
nested Python dict object with the following keys and values:
label

A localized label for the collection of licenses.

licenses
An array of Python dict objects, each of which describes one
license. These dict objects have the following keys and values:
label

A localized label for the license.

licenseid
The ID of the license.

794

IBM Cloud Orchestrator 2.4.0.2: User's Guide

text

The localized text of the license.

The value of the licenses attribute is generated by the product and cannot
be set. The value of the dict object is not protected against updates, but
such changes have no effect.
licenseaccepted
This attribute indicates if the license from this virtual image has been
accepted. IBM Cloud Orchestrator does not allow a virtual image to be
used until the license is accepted. The license from the virtual image must
be retrieved before it can be accepted. The following values are valid:

name

'T'

The virtual image license has been accepted.

'F'

The virtual image license has not been accepted.

The display name associated with this virtual image. This attribute is
generated automatically when the virtual image is imported. This field
contains a string value with a maximum of 1024 characters.

operatingsystemdescription
This attribute specifies a textual description of the operating system used
by the virtual image. The value of this attribute is a string and might be
None if the OVA of the virtual image does not supply a value.
operatingsystemid
The readonly attribute specifies the ID of the guest operating system used
by the virtual image. The value of this attribute is an integer that
corresponds to one of the constants defined for
CIM_OperatingSystem.OSType.
operatingsystemversion
This read-only attribute specifies the version of the guest operating system
used by the virtual image. The value of this attribute is a string and might
be None if the OVA of the virtual image does not supply a value.
owner

A user object that references the owner of this virtual image. This attribute
is an integer value. For more information about the properties and
methods supported by user objects, enter the following command:
>>> help(deployer.user)

parts

The parts that can be realized by this virtual image. For more information
about the operations available for this list of parts, see Parts on the
command-line interface on page 839. You can also get help for
deployer.parts, as shown in the following example:
>>> help(deployer.parts)

pmtype The type of machine supported by this virtual image. This field contains a
string value with a maximum of eight characters.
productids
This attribute specifies all of the product IDs associated with this virtual
image.
servicelevel
The service level of the attribute. This field contains a string value with a
maximum of 1024 characters.
updated
The time the virtual image was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the virtual image is displayed, this
value is shown as the date and time in the local time zone.
Chapter 11. Reference

795

version
The version of the virtual image. This field contains a string value with a
maximum of 1024 characters.

VirtualImage methods
The VirtualImage object has the following methods:
acceptLicense(licenses)
This method accepts the license presented by the virtual image. The IBM
Cloud Orchestrator cannot use a virtual image until you have accepted its
license. This method accepts a single optional parameter that allows you to
specify which license for this virtual image is being accepted. The value for
this parameter must be a Python dict object in which each key is a license
collection ID for the virtual image. Each value is the license ID for the
license to be accepted from that collection. If this parameter is not
supplied, the product behaves as if an arbitrary license from each license
collection has been accepted. The following example shows the usage of
this method:
>>> myvi.acceptLicense({ collection1: license3,
collection2: license17 })

For more information about virtual image licenses, enter the following
command:
>>> help(deployer.virtualimage.license)

addProductid
Adds a new product ID to all the virtual image parts. This method accepts
the following parameters:
productid
The product ID that you want to add. This parameter is required.
licensetype
The license type for this product ID. Valid values are:
v PVU
v Server
The default value is PVU. This parameter is required.
licensecpu
The processor count limit for a server license. This parameter is
required for the server license type.
licensememory
The memory limit in GB for a server license. This parameter is
required for the server license type.
The following example shows the addProductid method:
>>> myimage[0].addProductid(5724-X89, PVU)
>>> myimage[0].addProductid(5724-X89, Server, 4, 32)

deleteProductid
Delete a product ID from all of the virtual image parts. This method
accepts the following parameters:
productid
The product ID that you want to delete. This parameter is
required.

796

IBM Cloud Orchestrator 2.4.0.2: User's Guide

licensetype
The license type for this product ID. Valid values are:
v PVU
v Server
The default value is PVU. This parameter is required.
The following example shows the deleteProductid method:
>>> myimage[0].deleteProductid(5724-X89, PVU)

For more information about working with resource objects, see the Resources,
resource collections, and methods on page 842 section.
You can control the user access to virtual images with the ACL object. For more
information about the ACL object, see the ACL object on page 862 information.
Related concepts:
Resources, resource collections, and methods on page 842
IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
Related tasks:
Chapter 6, Managing virtual images, on page 331
You can manage virtual images that can be deployed by using IBM Cloud
Orchestrator.
Related reference:
ACL object on page 862
You can use the access control list (ACL) object to set and control user access for
other IBM Cloud Orchestrator resources.
Virtual images REST API on page 985
You can use the representational state transfer (REST) application programming
interface (API) to manage virtual images.
Related information:
Jython
Python documentation

Virtual image mappings command-line interface reference

You can manage virtual image mappings using the IBM Cloud Orchestrator
command-line interface. Virtual image mappings represent association between
pattern engine virtual images and OpenStack images.
For information about working with the command-line interface, see the Using
the command-line interface on page 735 section.

VirtualImageMappings object
A VirtualImageMappings object represents the collection of virtual image mappings
defined to IBM Cloud Orchestrator. Objects of this type are used to create, delete,
iterate over, list and search for virtual image mappings on the IBM Cloud
Orchestrator.

Chapter 11. Reference

797

You can work with virtual image mappings on the command line and help is
available. To get help for the VirtualImageMappings object, pass it as an argument
to the help() function, as shown in the following example:
>>> help(deployer.virtualimagemappings)

VirtualImageMappings methods
The VirtualImageMappings object has the methods described for a typical resource
collection. The following method is unique to VirtualImageMappings as its
parameters and return values differ from what is expected:
create Creates a new virtual image mapping between pattern engine virtual
image and OpenStack image on IBM Cloud Orchestrator. The attributes to
create a new virtual images can be specified as a dict object in the
following ways:
v To create a mapping between pattern engine virtual image and already
existing OpenStack image using the OpenStack image UUID:
>>> deployer.virtualimagemappings.create({templateid: 1, cloudid: 2,
region: RegionOne, uuid: edd897e3-cd48-4a6f-8dd2-d6c3d11c0375})

v To create a mapping between pattern engine virtual image and new

OpenStack image created by transferring the virtual image disk file to
OpenStack region. This operation applies only to virtual images built on
a single disk file:
>>> deployer.virtualimagemappings.create({templateid: 1, cloudid: 2,
region: RegionOne})

This method returns a VirtualImageMapping object for the newly created

mapping. Image transfer operation might take significant amount of time
depending on the image disk size and it is therefore queued on the pattern
engine task queue.
Tip: The dict attributes templateid and cloudid values can be set to
VirtualImage and Cloud objects instead of integer identifiers respectively.

VirtualImageMapping object
A VirtualImageMapping object represents a relation between a particular virtual
image defined to IBM Cloud Orchestrator pattern engine and an image defined in
OpenStack region. Use the VirtualImageMapping object to query and manipulate
the virtual image mapping definition in IBM Cloud Orchestrator. Attributes of the
virtual image mapping resource and relationships between the virtual image
mapping and other resources in IBM Cloud Orchestrator are represented as Jython
attributes on the VirtualImageMapping object. Manipulate these Jython attributes
using standard Jython mechanisms to change to the corresponding data on the
IBM Cloud Orchestrator.
You can work with a virtual image on the command line and help is available. To
get help for the VirtualImage object, pass it as an argument to the help() function,
as shown in the following example:
>>> help(deployer.virtualimagemapping)

VirtualImageMapping attributes
The VirtualImageMapping object has the following attributes, all which are read
only:

798

IBM Cloud Orchestrator 2.4.0.2: User's Guide

created
The creation time of the virtual image mapping, as number of seconds
since midnight, January 1, 1970 UTC. When the virtual image mapping
displays, this value is shown as the date and time in the local time zone.
currentstatus
The status of the virtual image mapping. This field contains an eight
character string value that is generated by the product.
id

The ID of the virtual image mapping. This attribute is an integer value.

name

The display name associated with this virtual image mapping. This
attribute is generated automatically when the virtual image mapping is
created and it is the same as the virtual image name. This field contains a
string value with a maximum of 1024 characters.

region The name of the OpenStack region in which the mapped OpenStack image
is located. This field contains a string value with a maximum of 1024
characters.
templateid
The ID of the virtual image. This attribute is an integer value.
uuid

The UUID of the mapped OpenStack image in region specified in region

attribute.

virtualimage
The nested VirtualImage object to which the OpenStack image is mapped.
This attribute value is a VirtualImage object.

Virtual machines command-line interface reference

You can administer the virtual machines by using the IBM Cloud Orchestrator
command-line interface.
For general information about working with the command-line interface, see the
Using the command-line interface on page 735 section.

VirtualMachines object
A VirtualMachines object represents the collection of virtual machines within a
virtual system instance on IBM Cloud Orchestrator. Objects of this type are used to
create, delete, iterate over, list and search for virtual machines within a virtual
system instance on IBM Cloud Orchestrator.
Help is available on the command-line interface for the VirtualMachines object. To
get help, pass the VirtualMachines object as an argument to the help() function, as
shown in the following example:
>>> help(deployer.virtualmachines)

VirtualMachine object
A VirtualMachine object represents a particular virtual machine defined on IBM
Cloud Orchestrator. Use the VirtualMachine object to query and manipulate the
virtual machine definition. Attributes of the virtual machine are represented as
Jython attributes on the VirtualMachine object. Relationships between the virtual
machine and other resources on the IBM Cloud Orchestrator are also represented
as Jython attributes on the VirtualMachine object. Manipulate these Jython
attributes using standard Jython mechanisms to change to the corresponding data
on the IBM Cloud Orchestrator.
Chapter 11. Reference

799

Help is available on the command-line interface for the VirtualMachine object. To

get help, pass the name of the object as an argument to the help() function, as
shown in the following example:
>>> help(deployer.virtualmachine)

VirtualMachine attributes
The VirtualMachine object has the following attributes:
cloud

A reference to the cloud to which this virtual machine belongs. For more
information about the properties and methods supported by cloud objects,
see Cloud group command-line interface reference on page 745 or enter
the following command:
>>> help(deployer.cloud)

cpucount
The number of virtual processors defined for this virtual machine. This
value is an integer.
created
The creation time of the virtual machine, as number of seconds since
midnight, January 1, 1970 UTC. When the virtual machine is displayed,
this value is shown as the date and time in the local timezone. This value
is numeric and is automatically generated by the product.
currentmessage
The message associated with the status of the virtual machine. This field
contains an eight character string value that is generated by the product.
currentmessage_text
Specifies the textual representation of the currentmessage attribute. This
attribute is a string representation of the currentmessage attribute in the
preferred language of the requester. This status message is automatically
generated by the product.
currentstatus
The status of the virtual machine. This field contains an eight character
string value that is generated by the product.
currentstatus_text
Specifies the textual representation of the currentstatus attribute. This
attribute is a string representation of the currentstatus attribute in the
preferred language of the requester. This status message is automatically
generated by the product.
desiredstatus
The intended status of the virtual machine. This field contains an eight
character string value that is generated by the product.
displayname
The display name associated with this virtual machine in the hypervisor.
This field contains a string value with a maximum of 1024 characters.
environment
The environment property shows the environment variables defined on the
virtual machine. The value of this property is a Jython dictionary (dict)
object.
Note: This dict object is intended only for reading. You can update the
dict object, but updates are not sent back to the IBM Cloud Orchestrator.
Therefore, updates have no effect on the virtual machine.

800

IBM Cloud Orchestrator 2.4.0.2: User's Guide

hardware
The hardware details for the virtual machine.
hypervisor
A reference to the hypervisor on which this virtual machine is running. For
more information on the properties and methods supported by Hypervisor
objects, enter:
>>> help(deployer.hypervisor)

If the hypervisor has been put in quiesce mode, the virtual machine can be
migrated to a new hypervisor by assigning a new Hypervisor to this
attribute, as shown in the following example:
>>> assert myvm.hypervisor.isQuiesced()
>>> myvm.hypervisor = newhypervisor

A list of suitable hypervisors can be obtained using the migrationtargets

attribute of the virtual machine. Setting the hypervisor attribute to None
causes IBM Cloud Orchestrator to select a new hypervisor for the virtual
machine.
hypervisormachineid
Specifies the ID assigned to the virtual machine by the hypervisor. This
field contains a string value with a maximum of 1024 characters.
id

The ID of the virtual machine. This value is numeric and is automatically

generated by the product.

ip

A reference to the IP address used by this virtual machine. For more

information about the properties and methods supported by IP objects, see
IP command-line interface reference on page 764 or enter the following
command:
>>> help(deployer.ip)

ips

A reference to the IP addresses assigned to this virtual machine. For more

information on the properties and methods supported by IP objects, see
IP command-line interface reference on page 764 or enter the following
command:
>>> help(deployer.ip)

memory
The amount of memory allocated to this virtual machine, in megabytes.
This value is an integer.
migrationtargets
A list of hypervisors to which the virtual machine can be migrated. A
value of None indicates that the hypervisor hosting the virtual machine has
not been quiesced. An empty list indicates no suitable hypervisors were
found. The returned list is mutable, but changes to the list have no effect.
name

The display name associated with this virtual machine. This field contains
a string value with a maximum of 1024 characters.

runtimeid
The runtime ID generated by the hypervisor on which this virtual machine
is running. This field contains a string value with a maximum of 1024
characters.
scripts
The scripts that have been run on the virtual machine, both during and
after deployment.
Chapter 11. Reference

801

storageid
The hypervisor storage ID of the storage on which this virtual machine
resides. This field contains a string value with a maximum of 1024
characters.
updated
The time the virtual machine was last updated, as number of seconds since
midnight, January 1, 1970 UTC. When the virtual machine is displayed,
this value is shown as the date and time in the local timezone. This value
is numeric and is automatically generated by the product.
virtualimage
A reference to the VirtualImage object from which this virtual machine
originated. For more information about the properties and methods
supported by VirtualImage objects, see Virtual images command-line
interface reference on page 792 or enter the following command:
>>> help(deployer.virtualimage)

virtualsystem
A VirtualSystem object that references the virtual system instance to which
this virtual machine belongs. For more information about the properties
and methods supported by VirtualSystem objects, see Virtual system
instances (classic) command-line interface reference on page 804 or enter
the following command:
>>> help(deployer.virtualsystem)

VirtualMachine methods
The VirtualMachine object has the following methods:
delete Deletes the resource represented by this object.
start() Starts a virtual machine.
stop() Stops a virtual machine. The virtual machine continues to reserve the
resource used by that virtual machine.
For more information about the command-line interface, see the Using the
command-line interface on page 735 section. For more information about working
with resources on the command-line interface, see the Resources, resource
collections, and methods on page 842 section.
You can control user access to virtual system instances using the ACL object. For
more information about the ACL object, see the ACL object on page 862 topic.
Related tasks:
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related information:
Jython
Python documentation

802

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Virtual system instances command-line interface reference

You can administer virtual system instances by using the IBM Cloud Orchestrator
command-line interface.
Note: The Virtualsysteminstances object is supported only for use with instances
that were deployed from virtual system patterns. It is not supported for use with
instances that were deployed from virtual system patterns (classic).

Virtualsysteminstances object
A virtualsysteminstances object represents the collection of virtual system
instances that are defined to the IBM Cloud Orchestrator. Objects of this type are
used to create, iterate over, list and search for virtual system instances. Objects of
this type are used to create, delete, iterate over, list and search for virtual system
instances on the IBM Cloud Orchestrator. The virtualsysteminstances object
supports methods that are not available with the VirtualSystems object.
Help is available on the command-line interface for the virtualsysteminstances
object. To get help, pass the virtualsysteminstances object as an argument to the
help() function, as shown in the following example:
>>> help(deployer.virtualsysteminstances)

Virtualsysteminstances methods
The Virtualsysteminstances object supports the following methods:
virtualsysteminstances()
List all virtual system instances.
Example:
>>> deployer.virtualsysteminstances()

virtualsysteminstances[index]
Get a specified virtual system instance by index.
Example:
>>> deployer.virtualsysteminstances[0]

virtualmachines()
List the virtual machines that are associated with a specified virtual system
instance.
Example:
>>> deployer.virtualsysteminstances.get("a-b62ae").virtualmachines()

findFixes()
List the fixes for the virtual system instance.
Example:
>>> vsysinst0 = deployer.virtualsysteminstances[0]
>>> vsysinstfixes = vsysinst0.findFixes()

Example output from this command:

[
{
"applicableto": [ "SourceNode" , "TargetNode"],
"appliedto": [ ],
"created": 1394115928843,
"currenteditionid": 140,
"currentmessage": None,
"currentstatus": "RM01012",
Chapter 11. Reference

803

"description": "",
"filename": "fix.zip",
"fixprereqs": [
{
"created": 1394115951541,
"fixid": 61,
"id": 62,
"middlewarename": "IBM WebSphere Application Server Liberty",
"middlewareversion": "8.5.5.0",
"updated": 1394115951541
}
],
"hasservicefile": "TRUE",
"id": 61,
"installtype": "WCA",
"name": "testfix",
"ownerid": 1,
"scriptid": 140,
"severity": "RM10388",
"target": "APPLICATION",
"type": "IFIX",
"updated": 1394447441222
]

applyFixes(Python dictionary object)

Install the specified fixes to the virtual system instance.
First, create a Python dictionary object to specify the fixes that you want to
install. Then, install the fixes by calling the applyFixes(Python dictionary
object) method. For example:
>>> vsysinst0 = deployer.virtualsysteminstances[0]
>>> vsysinstfixes = vsysinst0.findFixes()
>>> fixes = [{"vmtemplate":"SourceNode", "vmfixes":[vsysinstfixes[0] ]
{"vmtemplate":"TargetNode","vmfixes": [vsysinstfixes[0] ] } ]
>>> vsysinst0.applyFixes(fixes)

},

Note: You can get the value for vmtemplate, such as SourceNode and
TargetNode, from the output of the findFixes() method. For an example,
see the entry for the findFixes() method.
delete(virtual system ID)
Delete the specified virtual system instance.
Example:
>>> deployer.virtualsysteminstances.delete("a-b62ae")

Virtual system instances (classic) command-line interface

reference
You can administer virtual system instances (classic) by using the IBM Cloud
Orchestrator command-line interface.
Note: The VirtualSystems object is supported only for use with instances that
were deployed from virtual system instances (classic). It is not supported for use
with instances that were deployed from virtual system instances.
For general information about working with the command-line interface, see the
Using the command-line interface on page 735 section.

804

IBM Cloud Orchestrator 2.4.0.2: User's Guide

VirtualSystems object
A VirtualSystems object represents the collection of virtual system instances
defined to the IBM Cloud Orchestrator. Objects of this type are used to create,
delete, iterate over, list and search for virtual system instances on the IBM Cloud
Orchestrator.
Help is available on the command-line interface for the VirtualSystems object. To
get help, pass the VirtualSystems object as an argument to the help() function, as
shown in the following example:
>>> help(deployer.virtualsystems)

VirtualSystems methods
The VirtualSystems object has the following method:
create Creates a virtual system instance based on a pattern. This method accepts a
single parameter that describes the virtual system instance to be created.
This parameter can be any of the following:
v A dictionary (dict) object with the required and optional keys, as shown
in the following example:
>>> deployer.virtualsystems.create({name: my virtual system,
...
environmentprofile: myEnvProf, pattern: thepattern,
...
*.*.password: mypassword})

If a dict object is supplied, the following keys are recognized:

endtime
The time at which the virtual system instance is stopped,
expressed as the number of seconds since midnight, January 1,
1970 UTC. See the description of the starttime method for
additional details. This key is optional. If it is not specified, the
virtual system instance runs until it is manually stopped.
environmentprofile
A reference to the EnvironmentProfile object that specifies the
environment profile to be used for the virtual system instance.
See Environment profiles command-line interface reference on
page 748 or the `deployer.environmentprofiles help for more
information about obtaining an EnvironmentProfile object. This
key is required. The dict object must also include the cloud
groups, IP groups, IP address, and host names to be used for
deployment.
name

The name for the virtual system instance as a string. This key is
required.

pattern A reference to the Pattern object for the new virtual system
instance. See Virtual system patterns (classic) command-line
interface reference on page 818 or the deployer.patterns help
for more information about obtaining a Pattern object. This key
is required.
starttime
The time at which the virtual system instance is started,
expressed as the number of seconds since midnight, January 1,
1970 UTC. This value is most easily obtained using the Jython
time module, particularly the time.time() and time.mktime()
functions, as shown in the following example:
Chapter 11. Reference

805

>>>
>>>
>>>
>>>

# April 15th, 2009, 7am local time

time.mktime((2009,4,15,7,0,0,0,0,-1))
# 1 hour (3600 seconds) from now
time.time() + 3600

This key is optional. If it is not specified, the IBM Cloud

Orchestrator attempts to start the virtual system instance
immediately.
The dict object can also supply additional keys that specify the values
for part properties and script parameters required by the pattern. The set
of required properties and parameters depend on the pattern. Some
patterns might supply default values for all properties and parameters,
in which case no additional values are needed. If the pattern you
specified requires properties or parameters that you have not specified,
this method raises an exception. The exception indicates which
additional properties and parameters require values. You can also use
the listConfig() method on the pattern object to determine which part
properties and script parameters the pattern recognizes.
To specify a value for a part property, use a key in the following format:
part-<part_id>.<property_pclass>.<property_key>

The following example shows this format:

{ ..., part-1.ConfigPWD_ROOT.password: mypassword, ... }

Parameters for scripts are specified using a similar syntax, as the

following example shows:
part-<part_id>.script-<script_id>.<parameter_key>

The following example shows this format:

{ ..., part-1.script-1.NUM_WIDGETS: 10, ... }

For both part properties and script parameters, any of the three pieces of
the key can be an asterisk (*) to match any value for that piece. See the
following examples:
part-1.ConfigPWD_ROOT.password
Specifies the value for the root password on the part with ID 1.
*.ConfigUSER_ROOT.password
Specifies the user password for all the parts.
part-3.*.password
Specifies a value to be used for all the passwords for part 3,
including any script parameters that have a key of password.
*.*.password
Specifies a value to be used for all part properties and script
parameters with a key of password.
*.*.*

Specifies a value to be used for all part properties and script

parameters. This idiom is handled by the command-line
interface, but it is rarely useful.

If more than one key in the dict object can be used for a given part
property or script parameter, the most specific matching key is used. A
key with a wildcard closer to the end is considered less specific. For
example, when attempting to discover a value for part1.ConfigPWD_ROOT.password, the dict keys are considered in the
following order:
1. part-1.ConfigPWD_ROOT.password

806

IBM Cloud Orchestrator 2.4.0.2: User's Guide

2.
3.
4.
5.
6.

*.ConfigPWD_ROOT.password
part-1.*.password
*.*.password
part-1.ConfigPWD_ROOT.*
*.ConfigPWD_ROOT.*

7. part-1.*.*
8. *.*.*
For virtual image parts, you must specify the instance flavor in the
following format:
part-<part_id>.OpenStackConfig.flavor: <flavor>

where <flavor> is a value that describes the memory and storage

capacity of the virtual machine to be deployed and it might change
depending on the configuration of your OpenStack environment. By
default, the flavor values are:
m1.tiny
Memory: 512 MB, vCPUs: 1, Storage: 0 GB
m1.small
Memory: 2048 MB, vCPUs: 1, Storage: 20 GB
m1.medium
Memory: 4096 MB, vCPUs: 2, Storage: 40 GB
m1.large
Memory: 8192 MB, vCPUs: 4, Storage: 80 GB
m1.xlarge
Memory: 16384 MB, vCPUs: 8, Storage: 160 GB
Note: The flavor values might change depending on the configuration of
your OpenStack environment. In OpenStack, use the nova flavor-list
command to view the list of available flavors and their characteristics.
If an environment profile is used for the deployment, the dict object
must include specific information. The dict object must include
information about the cloud groups and IP groups to be used for each
part in the pattern. If the environment profile specifies that the IP
addresses are to be specified by the person deploying the pattern, then
the dict object must specify additional information. The dict object
must also include IP addresses for each part and can also include host
names for each part. This information is supplied in the dict object
using a syntax like that described for part properties and script
parameters. The following conventions are used for these keys:
part-<part_id>
Indicates the part to which the information applies, as with part
properties and script parameters.
vm-<vm_number>
For group parts, indicates a particular virtual machine to be built
when the part is deployed. The vm_number must be in the range
[1..part.count], inclusive. For example, if a group part has a
count value of 5 then the virtual machines are designated vm-1
through vm-5. For parts that do not belong to a group, part.count
is None, vm_number must always be 1. A single virtual machine
is designated vm-1.
Chapter 11. Reference

807

nic-<nic_number>
Indicates a particular network interface on the virtual machine.
All parts have at least one network interface, designated nic-1.
Additional network interfaces are designated in numeric order,
for example nic-2 and nic-3, if additional NIC add-ons have
been added to the part. The network interfaces are ordered the
same as the corresponding add-on pattern scripts in part.scripts.
The following keys in the dict object are used as the source of
environment profile deployment data:
part-<part_id>.cloud
Specifies a Cloud object for the cloud group to be used for the
part. The cloud group must be associated with the environment
profile.
Important: If a part represents a group of virtual machines, all
virtual machines must be in the same cloud group.
part-<part_id>.vm-<vm_number>.nic-<nic_number>.ipgroup
Specifies the IPGroup object to be used for the network interface.
The IP group must be associated with the cloud group in the
environment profile.
part-<part_id>.vm-<vm_number>.nic-<nic_number>.ipaddress
If the environment profile indicates that the user deploying the
pattern is to supply IP addresses, this key is used to supply the
IP address, or addresses, to be used for the network interface.
part-<part_id>.vm-<vm_number>.nic--<nic_number>.hostname
This key behaves like the IP address key, but it is used to
provide host names. Unlike IP addresses, host names are never
required. The semantics and syntax for single and multiple
values are identical to IP addresses. As with part properties and
script parameters, an asterisk (*) can be used to specify a value
that applies to more than one part, as shown in the following
example:
{ ..., \n
environmentprofile: myenvpro,
*.cloud: mycloud,
# all parts to one cloud
*.*.nic-1.ipgroup: ipgroup1, # all built-in intfs to
ipgroup1
part-1.vm-1.nic-1.ipaddress: 1.2.3.4,
part-1.vm-2.nic-1.ipaddress: 1.2.3.5,
part-3.vm-1.nic-1.ipaddress: 1.2.3.6,
part-3.*.nic-2.ipgroup: ipgroup2, # extra nic goes to
ipgroup2
part-3.vm-1.nic-2.ipaddress: 5.6.7.8
part-3.vm-1.nic-2.hostname: foo.mycompany.com,
... }

v The name of a file containing a Jython expression that evaluates to one

of the values in this list.
v The value deployer.wizard or a wizard instance created by calling
deployer.wizard(). If either of these values is supplied, the
command-line interface prompts interactively for the values to create the
virtual system instance. See Wizard objects on the command-line
interface on page 860 for more information about using the wizard to
create a VirtualSystem object.
v A list of any of the items previously listed, in which case multiple
virtual system instances are created, as shown in the following example:

808

IBM Cloud Orchestrator 2.4.0.2: User's Guide

>>> deployer.virtualsystems.create([vs1, {name:foo,...}])

VirtualSystem object
A VirtualSystem object represents a particular virtual system instance defined on
IBM Cloud Orchestrator. Use the VirtualSystem object to query and manipulate
the virtual system instance definition on the IBM Cloud Orchestrator. Attributes of
the virtual system instance and relationships between the virtual system instance
and other resources on the IBM Cloud Orchestrator are represented as Jython
attributes on the VirtualSystem object. Manipulate these Jython attributes using
standard Jython mechanisms to change the corresponding data on the IBM Cloud
Orchestrator.
To get help on the command-line interface for the VirtualSystem object, pass the
VirtualSystem object as an argument to the help() function, as shown in the
following example:
>>> help(deployer.virtualsystem)

VirtualSystem Attributes
The VirtualSystem object has the following attributes:
acl

The access control list for this virtual system instance. This field is
read-only. For additional help on using this object, enter the following
command:
>>> help(deployer.acl)

created
The creation time of the virtual system instance, as number of seconds
since midnight, January 1, 1970 UTC. When the virtual system instance is
displayed, this value is shown as the date and time in the local time zone.
This read-only value is numeric and is automatically generated by the
product.
currentmessage
The message associated with the status of the virtual system instance. This
read-only attribute has an eight character string value that is automatically
generated by the product.
currentmessage_text
Specifies the textual representation of the currentmessage attribute. The
currentmessage_text attribute is a string representation of the
currentmessage attribute in the preferred language of the requester. The
currentmessage attribute is automatically generated by the product.
currentstatus
The status of the virtual system instance. This read-only attribute has an
eight character string value that is automatically generated by the product.
currentstatus_text
Specifies the textual representation of the currentstatus attribute. The
currentstatus_text attribute s a string representation of the currentstatus
attribute in the preferred language of the requester. The
currentstatus_text attribute is automatically generated by the product.
desiredstatus
Indicates the status in which you want the virtual system instance to be.
Setting this value causes IBM Cloud Orchestrator to initiate the steps to get
the virtual system instance to this state.
Chapter 11. Reference

809

desiredstatus_text
Specifies the textual representation of the desiredstatus attribute. The
desiredstatus_text attribute is a string representation of the
desiredstatus attribute in the preferred language of the requester. The
desiredstatus_text attribute is automatically generated by the product.
environmentprofile
An environment profile object that references the profiles used to create
this virtual system instance. For more information about the properties and
methods supported by environment profile objects, see Environment
profiles command-line interface reference on page 748 or use the
following command:
>>> help(deployer.environmentprofile)

id

The ID of the virtual system instance. This value is numeric and is

automatically generated by the product. This field is read-only.

name

The name associated with this virtual system instance. Each virtual system
instance must have a unique name. This field contains a string value with
a maximum of 1024 characters. When a virtual system instance is created,
its name cannot be changed. This field is read-only.

owner

A User object that references the owner of this virtual system instance. For
more information about the properties and methods supported by User
objects, enter the following command:
>>> help(deployer.user)

pattern
A reference to the Pattern object from which this virtual system instance
was created. For more information about the properties and methods
supported by Pattern objects, see Virtual system patterns (classic)
command-line interface reference on page 818 or enter the following
command:
>>> help(deployer.pattern)

snapshots
A resource collection containing the snapshots taken of this virtual system
instance. For more information about the properties and methods
supported by the Snapshots objects, see Snapshots on the command-line
interface on page 781 or enter the following command:
>>> help(deployer.snapshots)

updated
The time the virtual system instance was last updated, as number of
seconds since midnight, January 1, 1970 UTC. When the virtual system
instance is displayed, this value is shown as the date and time in the local
time zone. This value is numeric and is automatically generated by the
product. This field is read-only.
virtualmachines
A resource collection containing the virtual machines within this virtual
system instance. For more information about the properties and methods
supported by the VirtualMachines objects, see Virtual machines
command-line interface reference on page 799 or enter the following
command:
>>> help(deployer.virtualmachines)

810

IBM Cloud Orchestrator 2.4.0.2: User's Guide

VirtualSystem methods
The VirtualSystem object has the following methods:
createSnapshot()
Creates a snapshot of this virtual system instance. This method takes an
optional dictionary that can contain a description for the snapshot.
delete()
Deletes the virtual system instance. This method accepts the following
optional parameters:
deleteRecord
This boolean parameter controls whether records and logs
associated with the virtual system instance are left on the product
machine after the virtual system instance is deleted. The default
value, True, deletes all information associated with the virtual
system instance. A value of False leaves those records on the
product machine for future inspection.
ignoreErrors
This boolean parameter controls whether the product continues
attempting to delete a virtual system instance after an error is
encountered. The default value, False, causes the attempted delete
to fail if an error is encountered.
Supply values for these parameters using Python named arguments, as
shown in the following example:
>>> myvirtsystem.delete(ignoreErrors=True, deleteRecord=False)

CAUTION:
Using the ignoreErrors parameter is helpful in specific situations only,
so use this option with caution. You might know that the virtual
machines cannot be deleted and you choose to clean them up manually,
for example. Or you might know that the server hosting the virtual
machine is no longer available. Therefore, deletion would not occur if
the errors blocked it. You can use the ignoreErrors parameter in these
circumstances to force deletion of a virtual system instance, even if the
virtual machines cannot be deleted.
start() Starts this virtual system instance.
stop() Stops this virtual system instance.
For more information about the command-line interface, see the Using the
command-line interface on page 735 section. For more information about working
with resources on the command-line interface, see the Resources, resource
collections, and methods on page 842 section.
You can control user access to virtual system instances using the ACL object. For
more information about the ACL object, see the ACL object on page 862 topic.
Related tasks:
Using the command-line interface on page 735
You can perform administrative functions in IBM Cloud Orchestrator by using the
command-line interface tool provided with the product.
Related information:
Jython
Chapter 11. Reference

811

Python documentation

Virtual system patterns command-line interface reference

You can work with virtual system patterns by using the VirtualSystemPattern and
VirtualSystemPatterns objects on the IBM Cloud Orchestrator command-line
interface.

VirtualSystemPatterns object
A VirtualSystemPatterns object represents the collection of virtual system patterns
on a IBM Cloud Orchestrator. Virtualsystempatterns objects are used to create,
iterate over, list and search for virtual system patterns.
Note: The VirtualSystemPatterns object is not supported for use with virtual
system patterns (classic). To work with virtual system patterns (classic), use the
Patterns object.
To get help for the VirtualSystemPatterns object on the command-line interface,
pass it as an argument to the help() function, as shown in the following example:
>>> help(deployer.virtualsystempatterns)

VirtualSystemPattern object
A VirtualSystemPattern object represents a single virtual system pattern or
template. Virtualsystempattern extends the Application object, and provides all
of the Application attributes and methods and the additional attributes and
methods that documented in subsequent sections.
Note: The VirtualSystemPattern object is not supported for use with virtual
system patterns (classic). To work with virtual system patterns (classic), use the
Pattern object.
To get help for the VirtualSystemPattern object on the command-line interface,
pass it as an argument to the help() function, as shown in the following example:
>>> help(deployer.virtualsystempattern)

VirtualSystemPattern attributes
patternversion
The pattern version, which can be any string. This attribute is read-only.
readonly
Boolean value that is set to true if the pattern is read-only, and false
otherwise. This attribute is read-only.

VirtualSystemPatterns methods
Create a virtual system pattern by using a Python dictionary (dict), a JSON file,
or a compressed file.
Format: deployer.virtualsystempatterns.create(file)
This example passes the method a Python dictionary (dict) that contains
the pattern application model:
>>> json={"model":{"name":"Test virtual system pattern", "patterntype":"vsys",
"version":"1.0", "patternversion":"1.0"}}
>>> deployer.virtualsystempatterns.create(json)

812

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This example passes the method a JSON file that contains the pattern
application model:
>>> deployer.virtualsystempatterns.create("F:\\cli\\testJson.json")

This example passes the method an exported pattern application model

that was saved to a compressed file (.zip):
>>> deployer.virtualsystempatterns.create("F:\\cli\\test.zip")

If you specify a JSON or compressed file, you can also specify one or more
of these optional parameters:
name
Specifies the pattern name, which overrides the pattern name that is
specified in the model.
patternversion
Specifies the virtual system pattern version, which overrides any
pattern version that is specified in the model. The patternversion is
set to 1.0 by default if it is not specified. This parameter can be set to
any string.
replace
Include this parameter and set it to true to replace an existing virtual
system pattern with the same name and version. If this parameter is
not included, or is set to false, the operation fails if the pattern exists.
Note: The patternversion and replace parameters are not currently
supported for use with virtual application patterns.
Example:
>>> deployer.virtualsystempatterns.create("F:\\cli\\vsys.zip", name = "Test",
patternversion = "2.0", replace = True)

List all virtual system patterns.

Format: deployer.virtualsystempatterns
Example:
>>> deployer.virtualsystempatterns

Get a single virtual system pattern by index.

Format: deployer.virtualsystempatterns[index]
Example:
>>> deployer.virtualsystempatterns[0]

Search for a virtual system pattern by the pattern name

Format: deployer.virtualsystempatterns["pattern_name"]
Example:
>>> deployer.virtualsystempatterns["Red Hat Satellite Server"]

If you only specify a portion of the pattern name, the command returns all
patterns that have that text string as part of the pattern name.
For example, to return all patterns that include the string Red Hat in the
pattern name, run the command:
>>> deployer.virtualsystempatterns["Red Hat"]

Search for virtual system patterns with a filter (Python dictionary)

Format: deployer.virtualsystempatterns.list(filter in dict format)
Chapter 11. Reference

813

Example:
>>> deployer.virtualsystempatterns.list({app_name:try1})

Share a pattern with another user

Format: deployer.virtualsystempatterns.get(pattern
ID).shareuser(user name,access rights)
Example:
>>> deployer.virtualsystempatterns.get("a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc").shareuser("tester","F")

Share a pattern with another group

Format: deployer.virtualsystempatterns.get(pattern
ID).sharegroup(group name,access rights)
Example:
>>> deployer.virtualsystempatterns.get("a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc").sharegroup("users","F")

Export the specified virtual system pattern.

Format: deployer.virtualsystempatterns[0].download(file path)
Example:
>>> deployer.virtualsystempatterns[0].download("C:\\sample.zip")

If you want to export or import a virtual system pattern and include the
referenced assets, use the export_artifacts and import_artifacts
methods from the deployer module.
Update the specified virtual system pattern.
Format: deployer.virtualsystempatterns.get(ID).update(file path)
Example:
>>> deployer.virtualsystempatterns.get("a-514a41").update("C:\\sample.zip")

List the images, script packages, add-ons, and software components (plug-ins)
that are associated with a pattern.
Format: deployer.virtualsystempatterns.listAssets()
Example:
>>> pattern = deployer.virtualsystempatterns[0]
>>> pattern.listAssets()

The output of the listAssets() method is a JSON object with each type of
asset that is associated with the pattern.
Clone a virtual system pattern from an existing virtual system pattern.
Format: deployer.virtualsystempatterns.get(ID).clone(name)
Example:
>>> deployer.virtualsystempatterns.get("a-514a41").clone("clonedTest")

Deploy the specified virtual system pattern.

Format: deployer.virtualsystempatterns.get(ID).deploy(deployment
name, cloud object or environment dictionary, certificate file
(optional), parameters (optional))
There are two options when you deploy a virtual system pattern through
the command-line interface:
1. Deploy the virtual system pattern with the placement that is
determined by the system, if applicable, or by not using placement if it
is not supported by the virtual system pattern. To deploy the virtual

814

IBM Cloud Orchestrator 2.4.0.2: User's Guide

system pattern with this method, call the deploy method and do not
include the placement_only parameter, or set it to False.
2. Modify the placement before you deploy the virtual system pattern,
and use the modified placement for the deployment. To use this
method, the deployment must be called in two phases:
v First, call the deploy method with the placement_only parameter set
to True to generate the placement and topology. This call generates a
Placement object without deploying the pattern. You can modify this
object to change the placement for the pattern before it is deployed.
This parameter tells the system to generate a placement for the
deployment, which is returned in response body. You can modify this
placement before you pass it to the system in the second phase to
deploy the pattern.
v Then, call the deployPlacement method and pass it a dictionary
object with these keys:
placement
This key is required. The value represents the final Placement
object. The placement settings that are specified in this object are
used for the deployment.
addon_parameters
This key is optional. Use this key to specify parameters for the
add-ons in the pattern, such as the volume ID for a Default
attach block disk add-on.
topology_parameters
This key is optional. Use this key to specify parameters for the
topology, such as the GPFS volume name.
This method accepts the following parameters:
name
Required. The name for the instance.
Cloud object or dictionary object
Required. You can use a cloud object or a dictionary object to describe
the environment profile. The environment profile dictionary object
contains these keys:
environment_profile
Required. An environment profile object.
placement_only
Optional. When placement_only is present and set to True, a
Placement object is returned without deploying the pattern. You
can modify the placement of the deployment by modifying this
object. Then, call the deployPlacement method and pass it the
modified object to use the modified settings for the deployment.
cloud_group
A Cloud object in the environment_profile. This attribute is
optional if the pattern supports placement.
ip_group
An IPGroup object in the cloud_group object. This attribute is
optional if the pattern supports placement.

Chapter 11. Reference

815

ip_version
Optional. Valid values are 'IPv4' and 'IPv6'. The default value is
'IPv4'.
The environment profile dictionary format is:
{
environment_profile: <env_profile_obj> or <env_profile_id>
placement_only: True or False,
cloud_group: <cloud_group_obj> or <cloud_group_id>
ip_group: <ip_group_obj> or <ip_group_id>
ip_version: IPv4 or IPv6
}

os Optional. Operating system type. Valid values are "Linux" and

"Windows".
productkey
License key for the Windows Operating System. This parameter is only
required when the os parameter is set to "Windows".
password
Windows password for Windows virtual machines. This parameter is
only required when the os parameter is set to "Windows".
file path of the public key for the instance
Optional. You can use ssh-keygen to generate SSH keys and save the
public key in a file.
Note:
v Because placement is handled by the system, you do not have to specify
a cloud group or IP group if an environment profile is specified. If the
pattern cannot use placement, then the cloud group and IP group
parameters are required. For example, if some of the plug-ins in the
pattern do not require Foundation 2.1, the application cannot use
placement. In this scenario, the cloud group and IP group are required.
If you do not specify these parameters for a pattern that cannot use
placement, the deployment fails.
v If "placement_only":True is provided, but placement is not supported
for the pattern, that parameter is ignored by the system. The pattern is
deployed as if the placement_only was not specified, or was set to False.
The format for <params> is:
{ "node_link_id.attributeId": attributeValue
"groups":{"node_link_id.groupId": True/False} (optional) }.

You must specify "groups" if there is group definition in the plug-in

metadata.
Example of a one-stage deployment:
sample= deployer.virtualsystempatterns.get(a-b62aeddb-6b43-4421-a0b6-df41b44c5407)
env=deployer.environmentprofiles[0]
cloud = env.clouds.keys()[0]
ipgroup=env.clouds[cloud].ipgroups.keys()[0]
deployOptions = {
"environment_profile" : env,
"cloud_group": cloud,
"ip_group": ipgroup,
"ip_version": "IPv4"
}
vsys = sample.deploy(env_test, deployOptions)

816

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Example of a two-stage deployment where the placement object is not

modified:
>>>
>>>
>>>
>>>
>>>

deploymentOptions = { "environment_profile":env, "placement_only":True }

sys=deployer.virtualsystempatterns.list({"sys_name":"Sample System"})[1]
vsys=sys.deploy("test",deploymentOptions)
// First stage deployment that returns placement object
p=vsys._getPlacement()
vsys.deployPlacement({placement:p})
// Second stage deployment using the returned placement.

Example of a two-stage deployment where the placement object is

modified:
>>>
>>>
>>>
>>>

deploymentOptions = { "environment_profile":env, "placement_only":True }

sys=deployer.virtualsystempatterns.list({"sys_name":"Sample System"})[1]
vsys=sys.deploy("test",deploymentOptions) // First stage deployment to collect placement
p=vsys._getPlacement()

Modify the placement object as needed. Then call deployPlacement and

pass it the updated placement object:
>>> vsys.deployPlacement({placement:p}) // Second stage of the deployment with updated placement

Example of a two-stage deployment where the placement object is

modified and the optional topology_parameters key is used:
>>> sample= deployer.virtualsystempatterns.get(a-b62aeddb-6b43-4421-a0b6-df41b44c5407)
// get your pattern
>>> env=deployer.environmentprofiles.list({"name":"System36"})[0] // get env profile
>>> deployOptions={"environment_profile":env, "placement_only":True}
// set deploy options and other parameters
>>> v=sample.deploy("test",deployOptions, sshFile, params)
// deploy first stage with sshFile and GPFS parameters
>>> p=v.getPlacement() // get placement
>>> deployOptionsForSecondStage={placement:p, topology_parameters:
{"GPFS-Manager.GPFS_Manager.Volume_Name_Main":["c0291f19-516a-4aeb-b9e1-351d913937c9"]}}
>>> v.deployPlacement(deployOptionsForSecondStage) // deploy final

Make the pattern read-only so that it cannot be modified.

Format:
deployer.virtualsystempatterns[index].makeReadOnly(check_unlocked_components)
Set the optional check_unlocked_components parameter to True to check for
unlocked components before the pattern is made read-only, or False (the
default value) to skip that check. If this parameter is set to True, the
command fails if the pattern contains any unlocked script packages,
add-ons, or images.
Note:
v The command fails if the pattern is already read-only.
v If the check_unlocked_components parameter is omitted or set to False, any
unlocked script packages, add-ons, or images in the pattern can still be
modified even though the pattern itself is read-only.
Important: Making a pattern read-only cannot be undone.
Examples:
>>> deployer.virtualsystempatterns[0].makeReadOnly()
>>> deployer.virtualsystempatterns[0].makeReadOnly("check_unlocked_components" : True)

Delete the specified virtual system pattern.

Format: deployer.virtualsystempatterns.delete(ID)
>>> deployer.virtualsystempatterns.delete("a-6aa5bf17-0c1e-457c-b135-7c8d19401109")

Chapter 11. Reference

817

Virtual system patterns (classic) command-line interface

reference
You can work with the pattern and patterns objects on the IBM Cloud
Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.
You can use the following resource objects to work with virtual system patterns
(classic):
ACL

You can control the access control list for virtual system patterns (classic)
with the ACL object. For more information about the ACL object, see ACL
object on page 862.

Advancedoptions
You can use the Advancedoptions object to view and set the advanced
options for the virtual system pattern (classic). Different advanced options
are available, depending on the topology described by your virtual system
pattern (classic). For more information about the Advancedoptions object,
see Advancedoptions object on page 825.
Parts

Represents the parts and collection of parts defined to IBM Cloud

Orchestrator. For more information about parts objects, see Parts on the
command-line interface on page 839.

Pattern_parts
Represents the virtual system pattern (classic) parts and collection of
virtual system pattern (classic) parts defined within a particular virtual
system pattern (classic) on IBM Cloud Orchestrator. For more information
about virtual system pattern (classic) parts, see Virtual system pattern
(classic) parts on the command-line interface on page 827.
Pattern_scripts
Represents the scripts and collections of scripts defined within a particular
virtual system pattern (classic) part on IBM Cloud Orchestrator. For more
information about the virtual system pattern (classic) script parts, see
Virtual system pattern (classic) scripts on the command-line interface on
page 833.
Patterns
Represents the virtual system patterns (classic) and collection of virtual
system patterns (classic) defined to IBM Cloud Orchestrator. For more
information about patterns, see Virtual system patterns (classic) on the
command-line interface on page 821.
User

A user can own virtual system patterns (classic).

Importing and exporting virtual system patterns (classic):

IBM Cloud Orchestrator virtual system patterns (classic) are topology definitions
for repeatable deployment that can be shared. You can export a command line
script that reconstructs a virtual system pattern on a different IBM Cloud
Orchestrator than the one on which it was created.
Before you begin
Before you can copy virtual system patterns from one IBM Cloud Orchestrator
environment to another IBM Cloud Orchestrator environment, you must first have

818

IBM Cloud Orchestrator 2.4.0.2: User's Guide

copied the virtual images, add-ons, and scripts. The same virtual images with the
same name must exist on both the environment before you can export and import
the virtual system patterns. Also, the same scripts and add-ons, with the same
names, must exist on both the IBM Cloud Orchestrator environments.
About this task
You can export virtual system patterns from one IBM Cloud Orchestrator
environment and import them to another IBM Cloud Orchestrator environment
using the patternToPython.py script. This command-line interface (CLI) script
examines a virtual system pattern defined on IBM Cloud Orchestrator and
generates another CLI script. When run, this generated CLI script reconstructs the
original virtual system pattern on another IBM Cloud Orchestrator environment.
The reconstructed virtual system pattern contains the same properties, shown in
the following list, as the original script:
v Parts
v Property values and metadata
v Scripts
v Script parameter values
v Advanced options
v Add-ons
v Add-on parameter values
v Status (draft or read-only)
Procedure
1. Use the samples/patternToPython.py CLI script to export the virtual system
pattern. Use the standard CLI parameters to specify the host name, user ID,
and password to access the virtual system pattern, and the location of the
patternToPython.py CLI script. Use one of the following methods to export a
virtual system pattern:
Interactively
Specify only the file name and select the virtual system pattern
interactively, as shown in the following example:
deployer -h <hostname.com> -u <user> -p <password>
-f samples/patternToPython.py -f exported_pattern.py

Automated
Specify both the file name and virtual system pattern, as shown in the
following example:
deployer -h <hostname.com> -u <user> -p <password>
-f samples/patternToPython.py -p "My Pattern" -f exported_pattern.py

See Invoking the command-line interface on page 737 for other ways to
specify the host name, user ID, and password.
The patternToPython.py CLI script accepts the following options:
-f <filename> or filename <filename>
Indicates that the generated CLI script is written to the specified file. If
not specified, the generated CLI script is written to standard output.
-p <pattern> or pattern <pattern>
Specifies the name of the virtual system pattern to be exported. The
virtual system pattern name you specify must uniquely identify a

Chapter 11. Reference

819

virtual system pattern. If you do not specify the virtual system pattern,
a list of virtual system patterns that are defined is shown and you are
prompted to select one.
passwords
Includes passwords in the Python code. If the password is not
specified, password values are omitted.
Remember: If you specify the --passwords option, passwords are
stored as plain text in the generated script. Restrict read access to the
script file accordingly.
2. Check for errors. If there are any problems generating the CLI script, the
patternToPython.py script generates error messages.
3. Run the generated CLI script to import the virtual system pattern to another
IBM Cloud Orchestrator environment. Use the standard CLI parameters to
specify the host name, user ID, and password of IBM Cloud Orchestrator on
which the virtual system pattern is to be created. The following example
specifies the host name and user ID:
deployer -h <hostname.com> -u <user> -p <password> -f exported_pattern.py

See Invoking the command-line interface on page 737 for more information
about specifying the host name, user ID, and password.
Results
When you have completed these steps, you have exported the virtual system
pattern from one IBM Cloud Orchestrator environment and imported it to a second
environment.
What to do next
You can use the virtual system patterns or modify them for use on the
environment to which you copied them.
Related tasks:
Making virtual system patterns (classic) read-only on page 463
Either draft or read-only virtual system patterns can be deployed for testing or
production, but making a virtual system pattern read-only prevents further edits to
the topology definition. Making virtual system patterns read-only provides
consistent reuse in the cloud.
Deploying a virtual system pattern (classic) on page 464
You can deploy virtual system patterns to run in a cloud group. You can deploy
either draft or committed virtual system patterns for testing or production.
Configuring advanced options on page 449
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Related reference:
Virtual system pattern (classic) editing views and parts on page 443
A virtual system pattern, that is not read-only, can be edited if you have
permission to edit it. The topology for a virtual system pattern is graphically
shown. Virtual image parts, add-ons, and script packages can be dropped onto an
editing canvas to create or change relationships between the parts that define the
topology.

820

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Virtual system patterns (classic) on the command-line interface:

You can work with virtual system patterns (classic) by working with Pattern and
Patterns objects on the IBM Cloud Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.
Patterns object
The Patterns object represents the collection of virtual system patterns defined to
IBM Cloud Orchestrator. Use objects of this type to create, delete, iterate over, list,
and search for virtual system patterns in IBM Cloud Orchestrator.
The Patterns object requires you to define the name attribute to create a virtual
system pattern. You can also specify a description using the description attribute.
To get help for the Patterns object on the command-line interface, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.patterns)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
Pattern object
A Pattern object represents a particular IBM Cloud Orchestrator virtual system
pattern. Use the Pattern object to query and manipulate the virtual system pattern
definition. Attributes of the virtual system pattern and relationships between the
virtual system pattern and other IBM Cloud Orchestrator resources are represented
as Jython attributes on the Pattern object. Manipulate these Jython attributes using
standard Jython mechanisms to change the corresponding IBM Cloud Orchestrator
data.
To get help for the Pattern object on the command-line interface, pass it as an
argument to the help() function, as shown in the following example:
>>> help(deployer.pattern)

Pattern attributes
acl

An object for manipulating the access control list for this virtual system
pattern. For more information about the properties and methods supported
by acl objects, enter the following command:
help(deployer.acl)

For more information, see ACL object on page 862.

advancedoptions
Use the advancedoptions object to view and set the advanced options for
the virtual system pattern. Different advanced options are available
depending on the topology described by your virtual system pattern. See
the detailed information in the Advancedoptions object on page 825
section.
created
The creation time of the virtual system pattern, as the number of seconds

Chapter 11. Reference

821

since midnight, January 1, 1970 UTC. When the virtual system pattern is
displayed, this value is shown as the date and time in the local time zone.
This field is read-only.
currentmessage
The message associated with the status of the virtual system pattern. This
field is read-only.
currentmessage_text
Provides a textual description of the current message. This field is
read-only.
currentstatus
The status of the virtual system pattern.
currentstatus_text
Provides a textual description of the status. This field is read-only.
description
The description of the virtual system pattern.
id

The ID of the virtual system pattern. This field is read-only.

name

The name associated with this virtual system pattern. Each virtual system
pattern must have a unique name.

owner

A User object that references the owner of this virtual system pattern. For
more information about the properties and methods supported by user
objects, enter the following command:
>>> help(deployer.user)

parts

A resource collection containing the parts contained within this virtual

system pattern. For more information about the properties and methods
supported by virtual system pattern parts objects, enter the following
command:
>>> help(deployer.pattern_parts)

updated
The time the virtual system pattern was last updated, as number of
seconds since midnight, January 1, 1970 UTC. When the virtual system
pattern is displayed, this value is shown as the date and time in the local
time zone. This field is read-only.
validations
The validation status and messages associated with the virtual system
pattern. The value of this attribute is a list containing the results of
validation tests run on the IBM Cloud Orchestrator. Each entry in the list is
a dict object containing the following keys and values:
status

This key provides the validation status associated with this entry.

status_text
This key provides a textual representation of the status.
message
This key provides the message that is associated with the status.
message_text
This key provides the textual representation of the message.
This value is automatically generated and cannot be changed. To get help
for the validations attribute, enter the following command:
help(deployer.pattern.validations)

822

IBM Cloud Orchestrator 2.4.0.2: User's Guide

validationmessage
The message associated with the validation status of the virtual system
pattern. This field is read-only.
validationmessage_text
Provides a textual description of the validation message. This attribute
provides a shortcut to access the first entry of the validations attribute.
This field is read-only.
validationstatus
The status associated with validation of the virtual system pattern. This
field is read-only.
validationstatus_text
Provides a textual description of the validation status. This attribute
provides a shortcut to access the first entry of the validations attribute.
This field is read-only.
virtualimage
The virtual image that is used to realize this virtual system pattern when
the virtual system pattern is deployed.
virtualsystems
The virtual system instances currently running this virtual system pattern.
For more information about the properties and methods supported by
virtualsystems objects, enter the following command:
help(deployer.virtualsystems)

Pattern methods
The pattern object has the following methods:
clone()
Clones this pattern object and returns a pattern object for the new virtual
system pattern, as shown in the following example:
clone(**options)

This method recognizes the following optional parameters:

description
The description for the new virtual system pattern. If not specified,
the description of the virtual system pattern being cloned is used.
name

The name assigned to the new virtual system pattern. If not

specified, the new virtual system pattern name is based on the
name of the virtual system pattern being cloned.

virtualimage
This deprecated parameter attempts to change all parts in the new
virtual system pattern to the specified virtual image, regardless of
the number of virtual images referenced in the original virtual
system pattern. To change the virtual image associated with parts
in the new virtual system pattern, set the virtualimage attribute on
those parts after the virtual system pattern has been cloned. If not
specified, parts in the new virtual system pattern use the same
virtual images as the corresponding parts in this virtual system
pattern. If specified, an attempt is made to switch all parts in the
new virtual system pattern to the indicated virtual image, as
shown in the following example:
>>> newpattern = mypattern.clone(name=foo, virtualimage=myvi)
Chapter 11. Reference

823

The following example shows the clone method:

>>> newpattern = mypattern.clone(name=foo, description=cloned pattern)

isDraft()
Indicates if this virtual system pattern is in draft mode.
isReadOnly()
Indicates if this virtual system pattern is read-only.
listConfig(data={})
Returns a dictionary (dict object) of the configurable part properties and
script parameters contained in this virtual system pattern. The keys for this
dict object are described under create in Virtual system instances (classic)
command-line interface reference on page 804 and in the online help for
deployer.virtualsystems.create. The values reflect the default values
defined in the virtual system pattern.
Accepts a single optional parameter that can be used to supply a dict
object containing overrides to the default values. Specify the overrides as
described under create method in Virtual system instances (classic)
command-line interface reference on page 804. Specifying overrides is
useful to see what values are to be used during a virtual system pattern
deployment without tying up the resources to perform an actual
deployment.
makeReadOnly()
Makes this virtual system pattern read-only. When the virtual system
pattern is read-only, the virtual system pattern can be deployed but not
modified.
runInCloud(cloud,options)
Allocates cloud resources and starts a copy of this virtual system pattern in
the cloud. This method requires the following parameters:
cloudorep
This is either a cloud object representing the cloud group in which
the virtual system pattern is to be run, or an EnvironmentProfile
object representing the environment profile to be used for the
deployment.
options A Jython dict object containing:
v A name key/value that specifies a name for the virtual system
instance to be created.
v The part property and script parameter values to be used for the
deployment. For more information, see the create method in
Virtual system instances (classic) command-line interface
reference on page 804.
v The environment profile configuration information. For more
information, see the create method in Virtual system instances
(classic) command-line interface reference on page 804.
The following example shows the runInCloud method:
>>> myvirtsys = mypattern.runInCloud(myCloud, { name: example,
...
*.*.password: thepassword })

toPython(f, **options)
This method generates a Python script on the local product machine that,
when run, reconstructs a virtual system pattern from IBM Cloud
Orchestrator. To use the generated script, the machine on which the virtual

824

IBM Cloud Orchestrator 2.4.0.2: User's Guide

system pattern is reconstructed must already contains the virtual image

and scripts used by the virtual system pattern.
This method takes, as a parameter, a file name or file object to which the
generated CLI script is saved. This method has no return value. Exceptions
are thrown if any errors are encountered while generating the Python
script.
Additional options can be passed to this method by including name=value
pairs in the method invocation, as shown in the following example:
mypattern.toPython(filename.py, includePasswords=True)

This method recognizes the following options:

includePasswords
A Boolean value that indicates if passwords are included in the
generated script. By default, the values for any part properties or
script parameters that are passwords are omitted from the
generated script.
Advancedoptions object
Use the Advancedoptions object to view and set the advanced options for the
virtual system pattern. Different advanced options are available, depending on the
topology described by your virtual system pattern. For some topologies, there are
no advanced options available.
Advancedoptions methods
The Advancedoptions property supports the following methods to view and set the
advanced options:
add(key)
Accepts a single parameter that must be either a string specifying an
advanced option or a list of these strings. The specified advanced options
are added to the existing advanced options for this virtual system pattern.
If any of the new advanced options conflict with advanced options that
were previously added, the new advanced options take precedence. If any
of the new advanced options depend on other advanced options that have
not already been set, the needed advanced options are automatically set.
The following example shows advanced options being set:
>>> mypattern.advancedoptions.add(messaging-enabled)
>>> mypattern.advancedoptions.add([sessionpersistence-db,
...
security-enabled])

clear() Clears all advanced options from the virtual system pattern. There are no
parameters to this method, as shown in the following example:
>>> mypattern.advancedoptions.clear()

__contains__(item)
Called implicitly by the Jython in operator, this method accepts a single
string parameter. The parameter names an advanced option and returns a
Boolean value. The boolean value indicates if the specified advanced
option is set in the virtual system pattern, as shown in the following
example:
>>> if security-enabled in mypattern.advancedoptions:
...
print security is enabled

Chapter 11. Reference

825

getAvailableOptions()
Returns a list of strings that name all the advanced options available for
this virtual system pattern. This method has no parameters, as shown in
the following example.
>>> mypattern.getAvailableOptions()

Note: This list of strings returned includes all available advanced options,
regardless of whether they are currently set.
To see just the options that are currently set, pass the advancedoptions
property to the Jython list() function.
__iadd__(other)
Started implicitly when you use the Jython += operator with the
advancedoptions property, as shown in the following example:
>>> mypattern.advancedoptions += messaging-engine-ha

The __iadd__ method has the same behavior as the add method.
__isub__(other)
This method is started implicitly when you use the Jython -= operator with
the advancedoptions property, as shown in the following example:
>>> mypattern.advancedoptions -= [messaging-mq-link,
...
messaging-enabled]

The __isub__ method has the same behavior as the remove method.
__iter__()
Returns an iterator over all the advanced options (as strings) that are
currently set for this virtual system pattern, as shown in the following
example:
>>> for ao in mypattern.advancedoptions:
...
print advanced option %s is set % ao

The __iter__ method is implicitly started when the advancedoptions

property is used in an iterative context
__len__()
Returns the number of advanced options currently set for the virtual
system pattern. This method is started implicitly by the Jython len
function, as shown in the following example:
>>> len(mypattern.advancedoptions)

remove(other)
This method accepts a single parameter that must be either a string
specifying an advanced option or a list of these strings, as shown in the
following example:
>>> mypattern.advancedoptions.remove(messaging-enabled)
>>> mypattern.advancedoptions.remove([sessionpersistence-db,
...
security-enabled])

The specified advanced options are removed from the existing advanced
options for this virtual system pattern.
Note:
v Some advanced options are grouped into sets that require at least one of
the advanced options to be set. If removing one advanced option would
cause this constraint to be violated, the default advanced option from
the set is automatically selected.

826

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Removing an advanced option does not automatically remove any

parent advanced options.

__repr__()
Returns a string representation of the advanced options. The string
representation includes short textual descriptions of each advanced option
and shows the hierarchy of the advanced options.
__str__()
Returns a string representation of the advanced options. The string
representation includes short textual descriptions of each advanced option
and shows the hierarchy of the advanced options.
__unicode__()
Returns a string representation of the advanced options. The string
representation includes short textual descriptions of each advanced option
and shows the hierarchy of the advanced options.
In addition to these methods, you can also assign a string or list of strings to the
advancedoptions property. The result is the same as if you had issued the clear()
and then the add() methods of the same advanced options.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
Related tasks:
Working with virtual system patterns (classic) on page 434
Using a virtual system pattern, you can describe the topology of a system that you
want to deploy. Virtual system patterns provide repeatable system deployment that
can be reproduced. To build virtual system patterns, you can use parts from one or
more virtual images, add-ons, and script packages.
Related information:
Jython
Python documentation
Virtual system pattern (classic) parts on the command-line interface:
You can work with virtual system patterns (classic) by working with virtual system
pattern (classic) parts on the IBM Cloud Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.
Pparts object
A pattern_parts object represents the collection of parts defined within a
particular virtual system pattern on the IBM Cloud Orchestrator. Objects of this
type are used to create, delete, iterate over, list and search for parts within a virtual
system pattern on the IBM Cloud Orchestrator. When creating a Ppart object, an ID
(of the part to be added to the virtual system pattern) is required. A Pparts object
has all the methods of a resourcecollection object. The create() method is
described because it has specific behavior unique to the Pparts object. The create
method creates a virtual system pattern part or parts within a virtual system
pattern. The parts to be added can be specified in any of the following ways:
v As a Part object for the part that is to be added to this virtual system pattern, as
shown in the following example:
Chapter 11. Reference

827

>>> mypattern.parts.create(thepart)

v As a dictionary (dict) object with the required keys, as shown in the following
example:
>>> mypattern.parts.create({id: thepart.id })

v As a long or int value that specifies the ID of the Part object to be used to create
a virtual system pattern part, as shown in the following example:
>>> mypattern.parts.create(thepart.id)

v As the name of a file containing a Jython expression that evaluates to one of the
values in this list.
v As the value deployer.wizard or a wizard instance created by calling
deployer.wizard(). If either of these values is supplied, the command-line
interface prompts interactively for the values to create the resource. For more
information about using the wizard to create a pattern_parts object, see
Wizard objects on the command-line interface on page 860.
v As a list of any of the previous items in the list, in which case multiple parts are
created within the virtual system pattern. This usage is shown in the following
example:
>>> mypattern.parts.create([part1, part2])

The create method returns a resource object for the new virtual system pattern
part, or a list of these objects if multiple virtual system pattern parts were created.
To get help for the pattern_parts object on the command-line interface, pass it as
an argument to the help() function, as shown in the following example:
>>> help(deployer.pattern_parts)

Ppart object
A Ppart object represents a part that has been added to a virtual system pattern in
IBM Cloud Orchestrator. Use the pattern_part object to query and modify the part
definition in the product. Attributes of the part and relationships between the part
and other resources in IBM Cloud Orchestrator are represented as Jython attributes
on the pattern_part object. Modify these Jython attributes using standard Jython
mechanisms to change the corresponding data in IBM Cloud Orchestrator.
Help is available for the virtual system pattern part object on the command-line
interface. To get help, pass it as an argument to the help() function, as shown in
the following example:
>>> help(deployer.pattern_part)

Ppart Attributes
The Ppart object has the following attributes:
count

The number of instances of this part that are to be created when the virtual
system pattern is deployed.
Note: This property is only defined for types of parts that can be
replicated at deployment time. For those types of parts, the count is
initially set to 1 and can be changed to any positive integer value. For
other types of parts, the count is None and cannot be changed.

countLocked
This attribute provides a boolean value that indicates if virtual machines,
based on this part, can be dynamically added to or removed from the

828

IBM Cloud Orchestrator 2.4.0.2: User's Guide

virtual system instance after the virtual system pattern has been deployed.
For parts that cannot be dynamically added or removed, the countLocked
attribute returns the None value and cannot be changed. For more
information, enter the following command:
help(deployer.pattern_part.countLocked)

description
The description of the part. This field is a string value with a maximum of
1024 characters.
id

The ID of the part. This numeric value is automatically generated by the

product.

partCaption
The label used for this part. This field is a string value with a maximum of
1024 characters.
pattern
The virtual system pattern that contains this part. For more information
about the properties and methods supported by pattern objects, enter the
following command:
>>> help(deployer.pattern)

properties
The list of properties defined for this part. Each property is a dict object
with the following properties:
key

The key of the property.

locked

Indicates whether the value of the userConfigurable property can

be changed.

pclass

The pclass value of the property.

value

The default value assigned to the property.

userConfigurable
Indicates whether the value of the property can be changed at
deployment time.
Note: This property is read-only. Changes to the dict object have no effect
on the part. To change a property of the part, use the setProperty() method
of the part.
scripts
A resource collection containing the scripts contained within this virtual
system pattern part. For more information about the properties and
methods supported by pattern_scripts objects, enter the following
command:
>>> help(deployer.pattern_scripts)

startsafter
The set of parts in the virtual system pattern that must start before this
part. For additional information on manipulating part startup order, enter
the following command:
>>> help(deployer.pattern_part.StartsAfter)

For more information, see StartsAfter object on page 831.

startuporder
The startup order of this part relative to other parts in the same virtual

Chapter 11. Reference

829

system pattern. Virtual system pattern parts with smaller values start
before virtual system pattern parts with larger values. This attribute is an
integer.
validations
This attribute provides the validation status and messages associated with
the virtual system pattern part. The value of this attribute is an array
containing the results of validation tests run on the IBM Cloud
Orchestrator. Each entry in the array is a dict object containing the
following keys and values:
message
This key provides the message that is associated with the status.
message_text
This key provides the textual representation of the message.
status

This key provides the validation status associated with this entry.

status_text
This key provides a textual representation of the status.
This value is automatically generated and cannot be changed. To get help
for the validations attribute, enter the following command:
help(deployer.pattern_part.validations)

virtualimage
The virtual image to be used to realize this part when the virtual system
pattern including the part is deployed. For more information about the
properties and methods supported by virtualimage objects, enter the
following command:
help(deployer.virtualimage)

Ppart Methods
The Ppart object has the following methods:
getProperty
Returns information about a particular property of a part. This method
accepts the following parameters:
key

The key of the property to be retrieved. This parameter is required.

pclass The pclass of the property to be retrieved. This parameter is

required.
wantMetadata
An optional boolean value indicating one of the following method
returns:
v Metadata about the property (True)
v Just the value of the property (False)
The following example shows the wantMetadata parameter:
>>> mypattern.parts[0].getProperty(ConfigPWD_ROOT,
password, True)

setProperty
Sets the value and (optionally) metadata for a part property. This method
accepts the following parameters:
key

830

The key of the property to be retrieved. This parameter is required.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

metadata
An optional dict object that can contain the userConfigurable key.
The userConfigurable key is a boolean value that indicates if users
can change the value of this property at deployment time.
pclass The pclass of the property to be retrieved. This parameter is
required.
value

An optional value to be set for the property. If not specified, the

current value of the property is unchanged.

The following examples show the setProperty method:

v >>> mypattern.parts[0].setProperty(ConfigPWD_ROOT, password,
...

mypassword, **{ userConfigurable: False })

v >>> mypattern.parts[0].setProperty(ConfigPWD_ROOT, password,

...

mypassword, userConfigurable=False)

StartsAfter object
A list-like object that represents the parts in the pattern that must start before this
part.
StartsAfter methods
The StartsAfter object has the following methods:
__contains__
This method is invoked implicitly by Jython when you use the in operator
on a StartsAfter object. Its single parameter must be a virtual system
pattern part from the same virtual system pattern. The method returns
True or False to indicate if the specified virtual system pattern part is in
the set of virtual system pattern parts that must start before the virtual
system pattern part to which the StartsAfter object belongs. Invocation of
this method is shown in the following example:
>>> firstPart = mypattern.parts[0]
>>> secondPart = mypattern.parts[1]
>>> if firstPart in secondPart.startsafter:
>>>
# firstPart starts before secondPart

__delitem__
This method is invoked implicitly by Jython when you use the del
operator on a StartsAfter object. Its single parameter must be the index of
the virtual system pattern part to be removed from the set of virtual
system pattern parts that must start before the virtual system pattern part
to which the StartsAfter object belongs. Invocation of this method is shown
in the following example:
>>> del mypattern.parts[0].startsafter[0]

__getitem__
This method is invoked implicitly by Jython when you use the [] operator
on a StartsAfter object. Its single parameter must be the non-negative index
of the virtual system pattern part to be returned from the set of virtual
system pattern parts that must start before the virtual system pattern part
to which the StartsAfter object belongs. Invocation of this method is shown
in the following example:
>>> mypattern.parts[0].startsafter[0]

__iadd__
This method is invoked implicitly by Jython when you use the += operator
Chapter 11. Reference

831

on the StartsAfter attribute of a virtual system pattern part. It accepts a

single parameter that can be either a virtual system pattern part or list of
virtual system pattern parts. All virtual system pattern arts must belong to
the same virtual system pattern. All parts passed as arguments are added
to the set ofvirtual system pattern parts that must start before the virtual
system pattern part to which the StartsAfter object belongs. Invocation of
this method is shown in the following example:
>>> firstPart = mypattern.parts[0]
>>> secondPart = mypattern.parts[1]
>>> secondPart.startsafter += firstPart

This method returns StartsAfter to allow chained operations.

isDeletable
Indicates if the specified virtual system pattern part can be removed from
the list of parts that start after this part.
__isub__
This method is invoked implicitly by Jython when you use the -= operator
on the StartsAfter attribute of a virtual system pattern part. It accepts a
single parameter that can be either a virtual system pattern part or list of
virtual system pattern parts. All virtual system pattern parts must belong
to the same virtual system pattern. All parts passed as arguments are
removed from the set of virtual system pattern parts that must start before
the virtual system pattern part to which the StartsAfter attribute belongs.
Invocation of this method is shown in the following example:
>>> firstPart = mypattern.parts[0]
>>> secondPart = mypattern.parts[1]
>>> secondPart.startsafter -= firstPart

This method returns the StartsAfter attribute to allow chained operations.

__iter__
This method is invoked implicitly by Jython when a StartsAfter object is
used in a context that requires iterating over its elements. It returns an
iterator over the virtual system pattern parts that are required to start
before the original virtual system pattern part.
__len__
Returns the number of virtual system pattern parts that are explicitly
required to start before the virtual system pattern part to which the
StartsAfter object belongs. This method is invoked implicitly by Jython
when you use the len() function, as shown in the following example:
>>> len(mypattern.parts[0].startsafter)

__lshift__
This method is invoked implicitly by Jython when you use the left shift
operator (<<) on a StartsAfter object. Its single parameter can be either a
virtual system pattern part or a list of virtual system pattern parts. All
virtual system pattern parts must belong to the same virtual system
pattern. All parts passed as arguments are added to the set of virtual
system pattern parts that must start before the virtual system pattern part
to which the StartsAfter object belongs. Invocation of this method is shown
in the following example:
>>> firstPart = mypattern.parts[0]
>>> secondPart = mypattern.parts[1]
>>> secondPart.startsafter << firstPart

This method returns the StartsAfter to allow chained operations.

832

IBM Cloud Orchestrator 2.4.0.2: User's Guide

__repr__
Returns a string representation of the virtual system pattern parts that
must start before a particular virtual system pattern part.
__rshift__
This method is invoked implicitly by Jython when you use the right shift
operator (>>) on a StartsAfter object. Its single parameter can be either a
virtual system pattern part or a list of virtual system pattern parts. All
virtual system pattern parts must belong to the same virtual system
pattern. All parts passed as arguments are removed from the set of virtual
system pattern parts that must start before the virtual system pattern part
to which the StartsAfter belongs. Invocation of this method is shown in the
following example:
>>> firstPart = mypattern.parts[0]
>>> secondPart = mypattern.parts[1]
>>> secondPart.startsafter >> firstPart

This method returns the StartsAfter object to allow chained operations.

__str__
Returns a string representation of the virtual system pattern parts that
must start before a particular virtual system pattern part.
__unicode__
Returns a string representation of the virtual system pattern parts that
must start before a particular virtual system pattern part.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
Related tasks:
Working with virtual system patterns (classic) on page 434
Using a virtual system pattern, you can describe the topology of a system that you
want to deploy. Virtual system patterns provide repeatable system deployment that
can be reproduced. To build virtual system patterns, you can use parts from one or
more virtual images, add-ons, and script packages.
Related information:
Jython
Python documentation
Virtual system pattern (classic) scripts on the command-line interface:
You can work with pattern_script and pattern_scripts objects on the IBM Cloud
Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.
Pscripts object
A pattern_scripts object represents the collection of scripts defined within a
particular virtual system pattern part in IBM Cloud Orchestrator. Objects of this
type are used to create, delete, iterate over, list, and search for scripts within a
pattern part in IBM Cloud Orchestrator.
When creating virtual system pattern scripts, the ID of the script to be added to
the pattern part is required. The pattern_scripts object has all the normal
Chapter 11. Reference

833

methods of a resourcecollection object. The create() method, however, has

behavior that is unique to the Pscripts object.
Help is available for the pattern_scripts object on the command-line interface. To
get help, pass it as an argument to the help() function, as shown in the following
example:
>>> help(deployer.pattern_scripts)

The Pscripts object has the following method:

create Creates a pattern script or scripts within a pattern part. The scripts to be
added can be specified in the following ways:
v As a script object for the part that is to be added to this pattern part,
as shown in the following example:
>>> mypart.scripts.create(thescript)

v As a dictionary (dict) object with the required keys, as shown in the

following example:
>>> mypart.scripts.create({id: thescript.id })

v As a long or int value that specifies the ID of the script object to be used
to create a virtual system pattern script. This value is shown in the
following example:
>>> mypart.scripts.create(thescript.id)

v As the name of a file containing a Jython expression that evaluates to

one of the values in this list.
v As the value deployer.wizard or a wizard instance created by calling
deployer.wizard(). If either of these values is supplied, the
command-line interface prompts, interactively, for the values to create
the resource. See Wizard objects on the command-line interface on
page 860 for more information about using the wizard to create a
pattern_scripts object.
v As a list of any of the previous parts specified, in which case multiple
scripts are created within the virtual system pattern part. This list of
parts is shown in the following example:
>>> mypart.scripts.create([script1, script2])

This method returns a virtual system pattern script object for the new
virtual system pattern script, or a list of these objects if multiple virtual
system pattern scripts were created.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
For more information about the script package object, see Script package
command-line interface reference on page 777.
Pscript object
A virtual system pattern script object represents a script that has been added to a
part in a virtual system pattern in IBM Cloud Orchestrator. Use the virtual system
pattern script object to query and manipulate the script definition in the product.
Attributes of the script and relationships between the script and other resources in
IBM Cloud Orchestrator are represented as Jython attributes on the virtual system
pattern script object. Manipulate these Jython attributes using standard Jython
mechanisms to change the corresponding data in IBM Cloud Orchestrator.

834

IBM Cloud Orchestrator 2.4.0.2: User's Guide

To get help for the pattern_script object, on the command-line interface, pass it as
an argument to the help() function, as shown in the following example:
>>> help(deployer.pattern_script)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
Pscript Attributes
The pattern_script object has the following attributes:
description
The description of the script.
executionOrder
Indicates the order in which this script is to run, relative to other scripts in
the same part. Virtual system pattern scripts with larger values for the
executionOrder attribute are run before scripts with smaller values. This
value is an integer.
id

The ID of the script. This attribute is read-only.

isdeletable
Indicates if this script can be deleted by a user. This attribute is read-only.
label

The label used for the script. This attribute is read-only.

parameters
A list of parameters defined for this script. This attribute is read-only. Each
parameter is a dict object with the following properties:
defaultvalue
The default value assigned to the parameter.
key

The key of the parameter.

locked

Indicates whether the value for the userConfigurable parameter can

be changed.
Note: This property is read-only.

userConfigurable
Indicates whether the value of the parameter can be changed at
deployment time.
Changes to the dict object have no effect on the script. To change a
parameter of the script, use the setParameter() method.
ppart

The part that contains this script. This attribute is read-only. For more
information about the properties and methods supported by pattern_part
objects, enter the following command:
>>> help(deployer.pattern_part)

startsafter
The set of scripts in the virtual system pattern that must start before this
script. For additional information on manipulating script startup order,
enter the following command:
>>> help(deployer.pattern_script.StartsAfter)

For more information, see StartsAfter object on page 831.

type

The type of this script. This attribute is read-only.

Chapter 11. Reference

835

Pscript Methods
The pattern_script part has the following methods:
getParameter
Returns information about a particular parameter of a script. This method
accepts the following parameters:
key

The key of the parameter to be retrieved. This parameter is

required.

wantMetadata
An optional boolean value indicating if the method returns
metadata about the parameter (True) or just the value of the
parameter (False), as shown in the following example:
>>> mypattern.parts[0].scripts[0].getParameter(key1, True)

setParameter
Sets the value and (optionally) metadata for a script parameter. This
method accepts the following parameters:
key

The key of the parameter to be set. This parameter is required.

defaultvalue
An optional value to be set for the parameter. If not specified, the
current value of the parameter is unchanged.
metadata
An optional dict object that can contain the following key:
userConfigurable
A boolean value that indicates if users can change the
value of this parameter at deployment time, as shown in
the following example:
>>> mypattern.parts[0].scripts[0].setParameter(key1, \
...
new value, **{ userConfigurable: False })

StartsAfter object
A list-like object that represents the parts in the pattern that must start before this
part.
StartsAfter methods
The StartsAfter object has the following methods:
__contains__
This method is invoked implicitly by Jython when you use the in operator
on a StartsAfter object. Its single parameter must be a virtual system
pattern script from the same virtual system pattern. The method returns
True or False to indicate if the specified virtual system pattern script is in
the set of virtual system pattern scripts that must start before the virtual
system pattern script to which the StartsAfter object belongs. Invocation of
this method is shown in the following example:
>>> firstScript = mypattern.parts[0].scripts[0]
>>> secondScript = mypattern.parts[1].scripts[0]
>>> if firstScript in secondScript.startsafter:
>>>
# firstScript starts before secondScript

__delitem__
This method is invoked implicitly by Jython when you use the del

836

IBM Cloud Orchestrator 2.4.0.2: User's Guide

operator on a StartsAfter object. Its single parameter must be the index of

the virtual system pattern script to be removed from the set of virtual
system pattern scripts that must start before the virtual system pattern
script to which the StartsAfter object belongs. Invocation of this method is
shown in the following example:
>>> del mypattern.parts[0].scripts[0].startsafter[0]

__getitem__
This method is invoked implicitly by Jython when you use the [] operator
on a StartsAfter object. Its single parameter must be the non-negative index
of the virtual system pattern script to be returned from the set of virtual
system pattern scripts that must start before the virtual system pattern
script to which the StartsAfter object belongs. Invocation of this method is
shown in the following example:
>>> mypattern.parts[0].scripts[0].startsafter[0]

__iadd__
This method is invoked implicitly by Jython when you use the += operator
on the StartsAfter attribute of a virtual system pattern script. It accepts a
single parameter that can be either a virtual system pattern script or list of
virtual system pattern scripts. All virtual system pattern scripts must
belong to the same virtual system pattern. All scripts passed as arguments
are added to the set ofvirtual system pattern scripts that must start before
the virtual system pattern script to which the StartsAfter object belongs.
Invocation of this method is shown in the following example:
>>> firstScript = mypattern.parts[0].scripts[0]
>>> secondScript = mypattern.parts[1].scripts[0]
>>> secondScript.startsafter += firstScript

This method returns StartsAfter to allow chained operations.

__isub__
This method is invoked implicitly by Jython when you use the -= operator
on the StartsAfter attribute of a virtual system pattern script. It accepts a
single parameter that can be either a virtual system pattern script or list of
virtual system pattern scripts. All virtual system pattern scripts must
belong to the same virtual system pattern. All scripts passed as arguments
are removed from the set of virtual system pattern scripts that must start
before the virtual system pattern script to which the StartsAfter attribute
belongs. Invocation of this method is shown in the following example:
>>> firstScript = mypattern.parts[0].scripts[0]
>>> secondScript = mypattern.parts[1].scripts[0]
>>> secondScript.startsafter -= firstScript

This method returns the StartsAfter attribute to allow chained operations.

__iter__
This method is invoked implicitly by Jython when a StartsAfter object is
used in a context that requires iterating over its elements. It returns an
iterator over the virtual system pattern scripts that are required to start
before the original virtual system pattern script.
__len__
Returns the number of virtual system pattern scripts that are explicitly
required to start before the virtual system pattern script to which the
StartsAfter object belongs. This method is invoked implicitly by Jython
when you use the len() function, as shown in the following example:
>>> len(mypattern.parts[0].scripts[0].startsafter)
Chapter 11. Reference

837

__lshift__
This method is invoked implicitly by Jython when you use the left shift
operator (<<) on a StartsAfter object. Its single parameter can be either a
virtual system pattern script or a list of virtual system pattern scripts. All
virtual system pattern scripts must belong to the same virtual system
pattern. All scripts passed as arguments are added to the set of virtual
system pattern scripts that must start before the virtual system pattern
script to which the StartsAfter object belongs. Invocation of this method is
shown in the following example:
>>> firstScript = mypattern.parts[0].scripts[0]
>>> secondScript = mypattern.parts[1].scripts[0]
>>> secondScript.startsafter << firstScript

This method returns StartsAfter to allow chained operations.

__repr__
Returns a string representation of the virtual system pattern scripts that
must start before a particular virtual system pattern script.
__rshift__
This method is invoked implicitly by Jython when you use the right shift
operator (>>) on a StartsAfter object. Its single parameter can be either a
virtual system pattern script or a list of virtual system pattern scripts. All
virtual system pattern scripts must belong to the same virtual system
pattern. All scripts passed as arguments are removed from the set of
virtual system pattern scripts that must start before the virtual system
pattern script to which the StartsAfter belongs. Invocation of this method is
shown in the following example:
>>> firstScript = mypattern.parts[0].scripts[0]
>>> secondScript = mypattern.parts[1].scripts[0]
>>> secondScript.startsafter >> firstScript

This method returns the StartsAfter object to allow chained operations.

__str__
Returns a string representation of the virtual system pattern scripts that
must start before a particular virtual system pattern script.
__unicode__
Returns a string representation of the virtual system pattern scripts that
must start before a particular virtual system pattern script.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
Related tasks:
Working with virtual system patterns (classic) on page 434
Using a virtual system pattern, you can describe the topology of a system that you
want to deploy. Virtual system patterns provide repeatable system deployment that
can be reproduced. To build virtual system patterns, you can use parts from one or
more virtual images, add-ons, and script packages.
Related information:
Jython
Python documentation

838

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Parts on the command-line interface:

You can work with the Part and Parts objects on the IBM Cloud Orchestrator
command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 735.
Parts object
A Parts object represents the collection of parts defined to IBM Cloud Orchestrator.
Objects of this type are used to delete, iterate over, list and search for IBM Cloud
Orchestrator parts. Parts cannot be manually created. Parts are created
automatically by IBM Cloud Orchestrator when a new virtual image is imported
into the system. Therefore, you must use the Parts attribute of a virtual image
when locating parts to be added to a virtual system pattern (classic).
To get help for the Parts object on the command-line interface, pass it as an
argument to the help() function, as shown in the following example:
>>> help(<virtualimage_name>.parts)

Part object
A Part object represents a particular part defined to IBM Cloud Orchestrator. Use
the Part object to query and manipulate the part definition. Attributes of the part
and relationships between the part and other resources in IBM Cloud Orchestrator
are represented as Jython attributes on the Part object. Manipulate these Jython
attributes using standard Jython mechanisms to change the corresponding data on
the IBM Cloud Orchestrator.
Help is available for the Part object on the command-line interface. To get help,
pass it as an argument to the help() function, as shown in the following example:
>>> help(deployer.part)

Part attributes
The Part object has the following attributes:
created
The creation time of the part, as number of seconds since midnight,
January 1, 1970 UTC. When the part is displayed, this value is shown as
the date and time in the local timezone. This value is numeric and is
automatically generated by the product. This attribute is read-only.
currentmessage
The message associated with the currentstatus of the part. This field is an
eight character string value that is automatically generated by the product.
This attribute is read-only.
currentmessage_text
Specifies the textual representation of the currentmessage attribute. This
field is a string representation of the currentmessage attribute in the
preferred language of the requester and is automatically generated by the
product. This attribute is read-only.
currentstatus
Specifies a string constant representing the currentstatus of the virtual
Chapter 11. Reference

839

system pattern. This field is an eight character string value that is

automatically generated by the product.
currentstatus_text
Specifies the textual representation of currentstatus. This string represents
the currentstatus in the preferred language of the requester and is
automatically generated by the product. This attribute is read-only.
description
The description of the part. This field is a string value with a maximum of
1024 characters. This attribute is read-only.
id

The ID of the part. This numeric value is automatically generated by the

product. This attribute is read-only.

label

The label of this part. This field is a string value with a maximum of 1024
characters. This attribute is read-only.

name

The name of this part. This field is a string value with a maximum of 1024
characters. This attribute is read-only.

owner

A User object that references the owner of this part. For more information
about the properties and methods supported by User objects, enter the
following command:
>>> help(deployer.user)

productids
This attribute specifies all of the product IDs associated with this virtual
image part.
updated
The time the part was last updated, as number of seconds since midnight,
January 1, 1970 UTC. When the part is displayed, this value is shown as
the date and time in the local timezone. This value is numeric and is
automatically generated by the product. This attribute is read-only.
validationmessage
The message associated with the validationstatus attribute of the part.
This attribute is read-only.
validationmessage_text
The textual representation of the validationmessage attribute. This
attribute is read-only.
validationstatus
The status associated with validation of the part. This attribute is read-only.
validationstatus_text
The textual representation of the validationstatus attribute. This attribute
is read-only.
virtualimage
A reference to the virtual image that defined this part. For more
information about the properties and methods supported by virtualimage
objects, enter the following command:
>>> help(deployer.virtualimage)

This value is automatically generated and cannot be changed. For more

information about working with virtual images on the command-line, see
Virtual images command-line interface reference on page 792.

840

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Part methods
The Part object has the following methods:
isConceptual
Indicates if this part is conceptual. A conceptual part is not tied to any
particular virtual image until deployment time.
addProductid
Add a new product ID to the virtual image part. This method accepts the
following parameters:
productid
The product ID that you want to add. This parameter is required.
licensetype
The license type for this product ID. Valid values are:
v PVU
v Server
The default value is PVU. This parameter is required.
licensecpu
The CPU count limit for this server license. This parameter is
required for the server license type.
licensememory
The memory limit in GB for this server license. This parameter is
required for the server license type, as shown in the following
example:
>>> mypart[0].addProductid(5724-X89, PVU)
>>> mypart[0].addProductid(5724-X89, Server, 4, 32)

deleteProductid
Delete a product ID from the virtual image part. This method accepts the
following parameters:
productid
The product ID that you want to delete. This parameter is
required.
licensetype
The license type for this product ID. Valid values are:
v PVU
v Server
The default value is PVU. This parameter is required.
The following example shows the deleteProductid method:
>>> mypart[0].deleteProductid(5724-X89, PVU)

For more information about working with resource objects, see Resources,
resource collections, and methods on page 842.
Related tasks:
Working with virtual system patterns (classic) on page 434
Using a virtual system pattern, you can describe the topology of a system that you
want to deploy. Virtual system patterns provide repeatable system deployment that
can be reproduced. To build virtual system patterns, you can use parts from one or
more virtual images, add-ons, and script packages.
Related information:
Chapter 11. Reference

841

Jython
Python documentation

Resources, resource collections, and methods

IBM Cloud Orchestrator manages different types of resources, for example,
patterns, virtual images, and virtual system instances. Within the command-line
interface, Jython objects are used to represent these resources and collections of
these resources. Methods control the behavior of the Jython objects.
An individual resource managed by IBM Cloud Orchestrator is represented in the
command-line interface by a Jython object. This object has the same attributes as
the IBM Cloud Orchestrator resource on the graphical interface, with some
additional methods and attributes to make it simpler to work with in the
command-line interface environment. Help is available for resource objects, in
general, and for each type of resource. You can get help for resources by entering
the following command:
>>> help(deployer.resource)

There are additional Jython objects that represent collections of resources in IBM
Cloud Orchestrator. These resource collections (Jython objects) can be used to
perform actions such as creating a resource or searching for an existing resource.
Help is available for resource collection objects, in general, and for each type of
resource collection. You can get help for resource collections by entering the
following command:
>>> help(deployer.resourcecollection)

Methods on the Jython objects support the operations that can be performed on the
resource within the IBM Cloud Orchestrator. When you call one of these methods
within the command-line interface tool, the request is sent over HTTPS to the IBM
Cloud Orchestrator where it is run. The result passes back over the HTTPS
connection to the command-line interface tool and is shown in one of the following
ways:
v As return values from the methods
v As an updated state in the Jython objects
v As Jython exceptions (if the result indicates an error condition)
All Jython classes, objects, and fields within the command-line interface are
documented using standard Jython doc strings. The help() function provided in
the command-line interface can be used to display the doc strings, as shown in the
following examples:
>>> help(deployer.ipgroups)
An IPGroups object represents the collection of IP groups defined to the
Workload Deployer appliance. Objects of this type are used to create, delete,
iterate over, list and search for IP groups on the Workload Deployer appliance.
Additional help is available for the following methods:
__contains__, create, delete, __delitem__, __getattr__, __getitem__,
__iter__, __len__, list, __lshift__, __repr__, __rshift__, __str__,
__unicode__
>>> help(deployer.ipgroup)
An IPGroup object represents a particular IP group defined on the
Workload Deployer appliance. Use the IP group object to query and
manipulate the IP group definition on the appliance. Attributes of
the IP group and relationships between the IP group and other
resources on the Workload Deployer appliance are represented as Jython

842

IBM Cloud Orchestrator 2.4.0.2: User's Guide

attributes on the IPGroup object. Manipulate these Jython

attributes using standard Jython mechanisms to make changes to the
corresponding data on the Workload Deployer appliance.
Additional help is available for the following methods:
__contains__, __delattr__, delete, __eq__, __hash__, isStatusTransient,
__nonzero__, refresh, __repr__, __str__, __unicode__, waitFor
Additional help is available for the following properties:
created, gateway, id, ips, name, netmask, networks, primarydns,
secondarydns, subnetaddress, updated
Remember to append an underscore to the property name when asking for
help using a specific instance of a resource rather than the class.
For example, "help(deployer.pattern.name)" or "help(mypattern.name_)"
will work, but "help(mypattern.name)" will resolve the name of the pattern
referenced by mypattern and attempt to provide help for the resulting
string rather than the property itself.
>>> help(deployer.ipgroup.subnetaddress)
Subnet address associated with the IP group, represented as a string in
dotted decimal notation (192.168.98.0, for example).

Resources on the command line

Any IBM Cloud Orchestrator functional object is a resource object on the
command-line interface. Within the command-line interface, Jython objects are
used to represent these resources. The IBM Cloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
The IBM Cloud Orchestrator command-line interface uses resources to represent
discrete objects managed by the IBM Cloud Orchestrator. For example, a particular
hypervisor, the WebSphere Application Server single server pattern, and the virtual
system instance you started yesterday would each be a resource.
A resource has a number of properties that describe it. Properties are used to
describe not only the attributes of the resource, such as its name or the time it was
created, but also its relationships to other resources. For example, many types of
resources have an owner property the value of which is the resource representing
the user that owns the resource. The following simple example shows a resource:
>>> deployer.self()
{
"currentmessage": "RM02012",
"currentmessage_text": "Inactive for more than five minutes",
"currentstatus": "RM01062",
"currentstatus_text": "Inactive",
"email": "",
"fullname": "Administrator",
"groups": (nested object),
"id": 1,
"parts": (nested object),
"password": (write-only),
"patterns": (nested object),
"roles": (nested object),
"scripts": (nested object),
"username": "cbadmin",
"virtualimages": (nested object),
"virtualsystems": (nested object)
}

Chapter 11. Reference

843

When displayed as a string, the properties of a resource are always shown within
curly brackets. In the previous example, the deployer.self() function returns a
single user resource that represents the current user. The following properties have
simple string or numeric values:
v currentmessage
v currentmessage_text
v currentstatus
v
v
v
v
v

currentstatus_text
email
fullname
id
username

The password property has a special value that indicates it can be written to, but
not displayed. The remaining properties all have a value of '(nested object)' that
indicates they have complex values which are not suitable for displaying, either
because doing this would require time-consuming data retrieval from the server or
because doing so would generate too much text. In the previous example, all these
additional properties are references to other resources or resource collections.
Resources are Jython objects and they can be used such as other Jython objects.
Jython variables can hold references to resource objects, as shown in the following
example:
>>> me = deployer.self()

The properties of the object can be read using the Jython dot operator, as shown in
the following example:
>>> me.fullname
Administrator
>>> me.id
1L

The properties of the object can be similarly updated, as shown in the following
example:
>>> me.email

>>> me.email = [email protected]

>>> me.email
[email protected]

Note: When you update a resource, the change is immediately sent to the IBM
Cloud Orchestrator.
The IBM Cloud Orchestrator command-line interface keeps a local cache of the
properties of the resource that are not relationship-based. This cache is
automatically refreshed whenever any of these properties are updated, and can be
manually refreshed at any time using the refresh() method.
If you try to perform operations not allowed by the product, a Jython exception is
raised, as shown in the following example:
>>> me.id = 143
Traceback (innermost last):
File "<console>", line 1, in ?
AttributeError: cant set attribute

844

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Some errors are detected by the IBM Cloud Orchestrator command-line interface
and others are detected by the IBM Cloud Orchestrator.
If you need more information about a particular resource, you can pass the
resource to the IBM Cloud Orchestrator command-line interface help function, as
shown in the following example:
>>> everyone = deployer.everyone()
>>> help(everyone)

To get help for a property of a resource object, append an underscore to the

property name, as shown in the following example:
>>> help(everyone.created_)

Most resources defined to IBM Cloud Orchestrator automatically track the time
and date they were created and last modified. Within the IBM Cloud Orchestrator,
these timestamps are tracked as the number of milliseconds since January 1, 1970
UTC. Because the Jython time and date libraries define timestamps as the number
of seconds since this epoch, the command-line interface code converts the number
of milliseconds returned from the IBM Cloud Orchestrator to seconds. The IBM
Cloud Orchestrator command-line interface formats these timestamps in the local
timezone whenever a string representation is generated for a resource object. The
following example retrieves the first ipgroup resource and displays the created
property for it, then the entire object is displayed from the interactive mode:
>>> ipg = deployer.ipgroups[0]
>>> ipg.created
1.242243975898E9
>>> ipg
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 13, 2009 3:46:15 PM
}

Many types of IBM Cloud Orchestrator resources also have status attributes that
reflect the current and intended status of the resource. The IBM Cloud Orchestrator
manages these status values and automatically adds an additional attribute with
_text appended to the name and containing a textual representation of this status,
as shown in the following example:
>>> ipg.ips[0].currentstatus
RM01017
>>> ipg.ips[0].currentstatus_text
Inactive

There are different types of relationships among the types of resources defined to a
IBM Cloud Orchestrator. When an individual resource is related to other resources,
additional attributes are added to the resource object pointing to the related
resource objects. If the relationship is to a single other resource, the attribute is
named the same as the type of other resource (singular) and its value is the other
resource object. If the relationship is to multiple other resources, the name of the
attribute is the type of the other resource (plural) and its value is a resource
Chapter 11. Reference

845

collection. In the following example, the relationship between an IP group and the
IP addresses it contains is represented by the ips property on the IP group object.
>>> ipg = deployer.ipgroups[0]
>>> ipg
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 13, 2009 3:46:15 PM
}
>>> ipg.ips
[
{
"created": May 13, 2009 3:47:54 PM,
"currentmessage": None,
"currentmessage_text": None,
"currentstatus": "RM01017",
"currentstatus_text": "Inactive",
"id": 5,
"ipaddress": "10.1.2.3",
"ipgroup": (nested object),
"updated": May 13, 2009 3:47:54 PM
},
{
"created": May 13, 2009 3:47:54 PM,
"currentmessage": None,
"currentmessage_text": None,
"currentstatus": "RM01017",
"currentstatus_text": "Inactive",
"id": 6,
"ipaddress": "10.1.2.4",
"ipgroup": (nested object),
"updated": May 13, 2009 3:47:54 PM
}
]

Note: In the previous example the value of the ips property is a list of IP address
objects.
Conversely, an IP address is related to a single IP group. This relationship is
represented by the ipgroup property on the IP object, as shown in the following
example:
>>> ip = ipg.ips[0]
>>> ip
{
"created": May 13, 2009 3:47:54 PM,
"currentmessage": None,
"currentmessage_text": None,
"currentstatus": "RM01017",
"currentstatus_text": "Inactive",
"id": 5,
"ipaddress": "10.1.2.3",
"ipgroup": (nested object),
"updated": May 13, 2009 3:47:54 PM
}
>>> ip.ipgroup
{
"created": May 13, 2009 3:46:15 PM,

846

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 13, 2009 3:46:15 PM
}

Resource collections on the command line

IBM Cloud Orchestrator manages different types of resources, for example
hypervisors, patterns, virtual images, and virtual system instances. These resources
can be collected into groups of like objects called resource collections. Within the
command-line interface, Jython objects are used to represent these resource
collections.
Resource collections are Jython objects that represent collections of IBM Cloud
Orchestrator resources which have a specific characteristic in common. Resource
collections can be used to perform actions such as creating new resources, deleting
resources, listing resources, or searching for an existing resource. The IBM Cloud
Orchestrator command-line interface uses many different types of resource
collections, but they fall into two broad categories.
The first type of resource collection corresponds roughly to the top-level resources
in IBM Cloud Orchestrator. These are the resource types you can select directly
when using the IBM Cloud Orchestrator user interface. These types of resource
collections are accessed directly with objects defined in the IBM Cloud Orchestrator
Jython package.
The second type of resource collection represents collections of resources defined
by a relationship with another resource. For example, all the virtual machines
contained within a virtual system instance or the set of hypervisors attached to a
particular storage device. These resource collections are accessed with properties
on the resource object that anchors the relationship. The resource collections from
the previous examples are accessed using the virtualmachines property of a
virtual system instance resource, the users property of a group resource, and the
hypervisors property of a storage resource.
Regardless of the type, resource collections all share the same basic ability to list
and search for resources within the collection. One important difference between
the types of resource collections is the semantics of their create or add and delete
or remove operations:
v Top-level resource collections have create and delete operations. Create defines a
resource to IBM Cloud Orchestrator that did not exist previously. Similarly,
delete completely erases a resource from IBM Cloud Orchestrator.
v Relationship-based resource collections have both add operations and remove
operations. Add causes an existing resource to be included in the resource
collection. Remove takes the resource out of the collection. The resource must
exist before being added to the collection and it continues to exist after it has
been removed.
The resource collections you are most likely to use are the resource collections that
represent all resources of a given type, for example all patterns, or all IP groups.

Chapter 11. Reference

847

These resource collections are available as attributes on the IBM Cloud

Orchestrator package, as shown in the following example:
>>> deployer.ipgroups
[
{
"created": May 13, 2009 3:46:15
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 13, 2009 3:46:15
},
{
"created": May 13, 2009 4:51:02
"gateway": "",
"id": 4,
"ips": (nested object),
"name": "192.168.0.0",
"netmask": "255.255.255.0",
"networks": (nested object),
"primarydns": "192.168.0.1",
"secondarydns": "",
"subnetaddress": "192.168.0.0",
"updated": May 13, 2009 4:51:02
}
]

PM,

PM
PM,

PM

The IBM Cloud Orchestrator package defines one of these types of resource
collections for each type of resource that IBM Cloud Orchestrator manages. The
previous example also shows another type of resource collection. When a resource
is related to other resources of a given type, the resources to which it is related are
represented as a resource collection. In the previous output, for example, the
networks attribute on each IP group represents the networks attached to the IP
group and the ips attribute represents the IP addresses defined within the IP
group. These types of resource collections can only be accessed through a resource
object.

Resource methods on the command-line interface

All IBM Cloud Orchestrator resources share methods that can be used to work
with resource objects.

Purpose
This topic describes the methods shared by all IBM Cloud Orchestrator resources.
For more information about resources, see Resources on the command line on
page 843.
The help for each type of resource indicates what methods and properties are
defined for that type of resource. To get additional help on a particular method,
use the help function with the method name appended to the resource in one of
the following ways:
v You can use the generic type of the resource, as shown in the following example:
>>> help(deployer.group)
>>> help(deployer.group.refresh)

v You can use a specific resource instance, as shown in the following example:

848

IBM Cloud Orchestrator 2.4.0.2: User's Guide

>>> everyone = deployer.everyone()

>>> help(everyone)
>>> help(everyone.refresh)

Do not put parentheses after the method name, for example

help(everyone.refresh()). This format causes the method to be invoked and the
help function attempts to provide help about whatever value the method returned
instead of the function method itself.
The provided examples assume the following IP groups are defined:
>>> ipg = deployer.ipgroups[0]
>>> ipg
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 13, 2009 3:46:15 PM
}

Properties
Each IBM Cloud Orchestrator resource is represented by a Jython object in the
command-line interface. Attributes of the resource are represented as properties of
the Jython object and can be accessed and updated using the typical Jython
mechanisms. Use the Jython dot operator or built-in getattr() function to obtain
the value of a property, as shown in the following example:
>>> ipg.name
ten
>>> getattr(ipg, name)
ten

The Jython dot operator or built-in setattr() function can be used to update the
value of a property, as shown in the following example:
>>> ipg.primarydns = 10.0.0.10
>>> ipg.primarydns
10.0.0.10
>>> setattr(ipg, name, new name for ten)
>>> ipg.name
new name for ten

The Jython built-in hasattr() function can be used to determine if a resource has a
given property, as shown in the following example:
>>> hasattr(ipg, netmask)
1
>>> hasattr(ipg, undefinedproperty)
0

Different types of resources have different properties defined. See the interactive
help that describes how to use specific types of resources in the command-line
interface for more information about the properties for each type of resource.
Command-line interface resource object reference on page 740 also provides a
listing of resources and resource collections with links to more information about
them.
Chapter 11. Reference

849

Methods
IBM Cloud Orchestrator resource methods include:
__contains__(item)
Indicates if this resource object has a value for the specified attribute. This
method is invoked implicitly by the Jython in operator, as shown in the
following example:
>>> address in ipg
1
>>> foo in ipg
0

__delattr__(name)
Removes an attribute for this resource in IBM Cloud Orchestrator. The update
is sent immediately to the product and the cached attributes are updated if the
request is successful. This method is invoked implicitly by the Jython del
operator, as shown in the following example:
>>> ipg
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 13, 2009 3:46:15 PM
}
>>> del ipg.secondarydns
>>> ipg
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": None,
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 10:11:27 AM
}

delete()
Deletes a resource from the IBM Cloud Orchestrator, as shown in the following
example:
>>> ipg in deployer.ipgroups
1
>>> ipg.delete()
>>> ipg in deployer.ipgroups
0

__eq__(other)
Indicates if another resource object represents the same resource as this object.
Note: This method tests if the two objects see the same resource on the IBM
Cloud Orchestrator. It does not check for a match between the cached
attributes of the two objects.

850

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This method is invoked explicitly for the Jython == operator and other
situations in which Jython determines if two objects are equal, as shown in the
following example:
>>> ipg == deployer.ipgroups[0]
1
>>> ipg == deployer.ipgroups[1]
0

__hash__()
Called implicitly by Jython when a resource object is used as a key in a
dictionary (dict) or when the built-in hash() function is called with a resource
object. This method returns a hash value for the resource.
Note: If two resource objects represent the same resource, the __hash__()
functions always return the same value. You cannot make any other
assumptions about the value returned by this function.
The __hash__() function is shown in the following example:
>>> hash(ipg)
1929121056

isStatusTransient()
Indicates if the currentstatus of this resource is transient. A status is
considered transient if IBM Cloud Orchestrator eventually brings the resource
out of this state without any user interaction. This method is invoked with no
parameters and returns the True or False values.
If the resource object does not have a currentstatus property, an exception is
raised.
Note: This method examines the cached value of the currentstatus property.
If you are polling the object to check its status, then use the refresh() method
to update the currentstatus from the product, as shown in the following
example:
>>> while myvirtualsystem.refresh().isStatusTransient():
...
time.sleep(5)

Alternatively, use the waitFor() method. The waitFor() method encapsulates

the refresh() and isStatusTransient() idiom into a single call.
__nonzero__()
Called implicitly by Jython when a resource object is used in a boolean context,
this method always returns True, as shown in the following example:
>>> if ipg:
...
print true
... else:
...
print false
...
true

refresh()
Updates the attributes of a resource. To reduce network traffic, the IBM Cloud
Orchestrator command-line interface caches a local copy of the attributes, but
not the relationships, of a resource. Use this method to update resource
attributes with current data from the IBM Cloud Orchestrator, as shown in the
following example:
>>> ipg.gateway
10.0.0.1
(change ipgroup gateway from a different CLI or GUI)
Chapter 11. Reference

851

>>> ipg.gateway
10.0.0.1
>>> ipg.refresh()
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.43",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": None,
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 10:27:23 AM
}
>>> ipg.gateway
10.0.0.43

__repr__()
This method is invoked implicitly by Jython when an expression entered in
interactive mode returns a resource object or when a resource object is passed
to the Jython repr() function. It returns a representation of the resource, as
shown in the following example:
>>> ipg
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 26, 2009 10:15:56 PM
}

__str__()
Returns a string representation of this resource. Attributes representing other
resources or resource collections are shown as (nested object) to avoid
recursive loops. Attributes representing timestamps are automatically
formatted in the local time zone. This method is called implicitly when a
resource is printed, for example if a Jython expression entered in interactive
mode returns a resource. It can also be invoked explicitly by passing a resource
collection to the Jython str() function.
>>> ipg
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 10:33:17 AM
}

__unicode__()
Returns a Jython Unicode string containing a string representation of the

852

IBM Cloud Orchestrator 2.4.0.2: User's Guide

resource. This method is called implicitly when a resource object is passed to

the Jython unicode() function or used in a context that requires a Unicode
string, as shown in the following example:
>>> unicode(ipg)
u{\n "created": May 13, 2009 3:46:15 PM,\n "gateway": "10.0.0.1",\n
"id": 2,\n "ips": (nested object),\n "name": "ten",\n "netmask":
"255.0.0.0",\n "networks": (nested object),\n
"primarydns": "10.0.0.2",\n "secondarydns": "10.0.0.3",\n
"subnetaddress": "10.0.0.0",\n
"updated": May 26, 2009 10:15:56 PM\n}

waitFor(condition, maxWait, interval)

The waitFor() method can be used to wait until a certain condition is true for
a particular resource. It accepts the following parameters:
condition
An optional object that can be called. The waitFor() method calls this
object periodically until it returns a value that evaluates to true. The
object that is called accepts the resource object as its only parameter. If
it is not specified, the following example shows the default value:
lambda r: not r.refresh().isStatusTransient()

That is, the default behavior is to refresh the cached properties of the
resource, and wait until the resource enters a non-transient state.
Note: This default value is only useful for resources that have a
currentstatus property. For other types of resources, you must
override the default condition with one of your own.
maxWait
The maximum amount of time to wait, in seconds, for the specified
condition to become true. Fractional seconds can be specified by
supplying a floating point value. A negative value causes this method
to wait indefinitely. The default value is -1.
interval
The interval at which to check the specified condition. The interval is
specified in seconds. Fractional seconds can be specified by supplying
a floating point value. The default value is 10, which causes the
condition to be evaluated once every 10 seconds.
The waitFor() method returns the value returned by the condition the last
time it was invoked. Arbitrary conditions can be supplied to this method, but
it is most often used to make a script wait for completion of a long-running
background process in IBM Cloud Orchestrator, such as importing a virtual
image or deploying a virtual system instance, as shown in the following
example:
>>> myvs = mypattern.runInCloud(...)
>>> myvs.waitFor()
>>> # myvs is now in either a started or failed state

Related concepts:
Resources on the command line on page 843
Any IBM Cloud Orchestrator functional object is a resource object on the
command-line interface. Within the command-line interface, Jython objects are
used to represent these resources. The IBM Cloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
Related information:
Chapter 11. Reference

853

Jython
Python documentation

Resource collections methods on the command-line interface

All IBM Cloud Orchestrator resource collections share methods that you can use to
work with these objects.

Purpose
This topic describes the methods shared by all IBM Cloud Orchestrator resource
collections. For more information about resource collections, see Resource
collections on the command line on page 847. The provided examples assume the
following IP groups are defined:
>>> deployer.ipgroups
[
{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 1:28:19 PM
},
{
"created": May 14, 2009 10:20:56 AM,
"gateway": "192.168.0.1",
"id": 6,
"ips": (nested object),
"name": "192.168.0.0",
"netmask": "255.255.255.0",
"networks": (nested object),
"primarydns": "192.168.0.2",
"secondarydns": "192.168.0.3",
"subnetaddress": "192.168.0.0",
"updated": May 14, 2009 1:28:52 PM
}
]

Methods
Resource collections methods include:
add(other)
Adds the specified resource or resources to this collection. This method accepts
a single parameter that can be either a resource or a list of resources. This
method has no return value; exceptions are raised to indicate any problems
adding the resources.
Note: This method does not create new resources. All resources passed to this
method must exist.
The following example shows the add(other) method:
>>> mygroup = deployer.groups.mygroup[0]
>>> joe = deployer.users.joe[0]
>>> mygroup.users.add(joe)

854

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Note: For relationship-based resource collections, the left shift operator ("<<")
can be used as an alias for the add() method, as shown in the following
example:
>>> mygroup.users << joe

__contains__(item)
Indicates if this resource collection contains the specified item. Because
resource collections contain resource objects, this method returns false unless
the item parameter is a resource object of the correct type. This method is
invoked implicitly by the Jython in operator, as shown in the following
example:
>>> ipg = deployer.ipgroups[0]
>>> ipg in deployer.ipgroups
1
>>> ipg in deployer.hypervisors
0

create(other)
Creates a resource or new resources and places them in this collection. The
attributes for the new resources can be specified in any of the following ways:
v As a dict object with the required keys, as shown in the following example:
>>> deployer.groups.create({name: new user group,
description: description of new group})

v As the name of a file containing a Jython expression that evaluates to one of

the values in this list.
v As the value deployer.wizard or a wizard instance created by calling
deployer.wizard(). If either of these values is supplied, the command-line
interface prompts interactively for the values required to create the resource.
See Wizard objects on the command-line interface on page 860 for more
information about using the wizard to create a resource object.
v As a list of any of the previous items in this list, in which case multiple
resources are created, as shown in the following example:
>>> deployer.groups.create([{name: new user group,
description: description of new group},
name_of_file_containing_jython_dict])

This method returns a resource object for the newly created resource, or a list
of resource objects if multiple resources were created.
Note: For type-based resource collections, the left shift operator, <<, can be
used as an alias for the create() method, as shown in the following example:
>>> deployer.groups << { name: new user group,
description: description of new group }

delete(other)
Deletes a resource in this collection. All information about this resource is
deleted from IBM Cloud Orchestrator. The resource to be deleted can be
specified in any of the following ways:
v As an int or long that specifies the ID of the resource to be deleted, as
shown in the following example:
>>> deployer.patterns.delete(17)

v As the resource object representing the resource to be deleted, as shown in

the following example:
>>> mypattern = deployer.patterns[4]
>>> deployer.patterns.delete(mypattern)

Chapter 11. Reference

855

This method raises exceptions to indicate any problems with deleting

resources.
Note: For type-based resource collections, the right shift operator, >>, can be
used as an alias for the delete() method, as shown in the following example:
>>> deployer.patterns >> mypattern

__delitem__(key)
Deletes an item from this resource collection. For resource collections based on
relationships, this removes the relationship between the resources; for resource
collections based on types, this method deletes the definition of the resource on
the IBM Cloud Orchestrator. The key parameter can be any type recognized by
the delete() or remove() methods.
The __delitem__(key) method is invoked implicitly by the Jython del
statement, as shown in the following example:
>>> for ipg in deployer.ipgroups:
...
print id %d: %s % (ipg.id, ipg.name)
...
id 2: ten
id 6: 192.168.0.0
>>> del deployer.ipgroups[6]
>>> for ipg in deployer.ipgroups:
...
print id %d: %s % (ipg.id, ipg.name)
...
id 2: ten

__getattr__(name)
Searches for a resource in the resource collection by name. Returns a list of
resource objects that matched the search criteria and returns an empty list if
none are found. For most types of resources, the string is matched against the
name of the resource.
Note: This match is a partial match therefore the returned list of resources can
include any names that contained the specified string anywhere in the name. If
any of the resources exactly match the specified string, they are provided at the
beginning of the returned list.
The descriptions for various types of resources specify if the __getattr__()
method searches on a different attribute. This method is invoked implicitly by
the Jython dot operator, as shown in the following example:
>>> deployer.ipgroups.te
[{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 1:28:19 PM
}]

__getitem__(key)
Returns a single resource from the collection. Unless otherwise indicated for a
specific type of resource collection, this method recognizes two types of key
values. If the value of the key parameter is an integer or long value, it is used
as an index into the collection and the specified item is returned. If the value
of the key parameter is a string, this method behaves as __getattr__(key).

856

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This method is invoked explicitly by Jython when square brackets are used
with a resource collection, as shown in the following example:
>>> deployer.ipgroups[1].subnetaddress
192.168.0.0
>>> deployer.ipgroups[en]
[{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 1:28:19 PM
}]

__iter__()
Returns an iterator that can be used to iterate over all resources in this
collection. This method is invoked implicitly by numerous Jython idioms
including:
v list comprehensions
v the for..in construct
v filter() function
v iter() function
v map() function
v reduce() function
v zip() function
The iterator is shown in the following example:
>>> [ ipg.name for ipg in deployer.ipgroups ]
[ten, 192.168.0.0]
>>> for ipg in deployer.ipgroups:
...
print ipg.subnetaddress
...
10.0.0.0
192.168.0.0
>>> filter(lambda ipg: ipg.name != ipg.subnetaddress, deployer.ipgroups)
[{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 1:28:19 PM
}]

__len__()
Returns the number of resources in the collection. In addition to the Jython
len() function, this method is invoked implicitly when a resource collection is
used in a boolean context. A resource collection that contains no resources is
considered false; a collection that contains at least one resource is considered
true, as shown in the following example:

Chapter 11. Reference

857

>>> len(deployer.ipgroups)
2
>>> if deployer.ipgroups:
...
print true
... else:
...
print false
...
true
>>> len(deployer.hypervisors)
0
>>> if deployer.hypervisors:
...
print true
... else:
...
print false
...
false

list(filt)
Returns a list of resources in this collection. An optional dict parameter can be
supplied to filter the list of resources returned. The keys and values in the dict
parameter are passed to IBM Cloud Orchestrator. The supported keys and
values within the dict parameter depend on the type of resource collection. The
list(filt) method is shown in the following example:
>>> deployer.ipgroups.list({name: t})
[{
"created": May 13, 2009 3:46:15 PM,
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 1:28:19 PM
}]

remove(other)
Removes a resource from this collection.
Note: The resource is not deleted from IBM Cloud Orchestrator, it is just
dissociated from this collection.
The resources to be removed can be specified in any of the following ways:
v As an int or long containing the ID of the resource to be removed.
v As the resource object for the resource to be removed, as shown in the
following example:
>>> mygroup = deployer.groups.mygroup[0]
>>> joe = deployer.users.joe[0]
>>> mygroup.users.remove(joe)

Note: For relationship-based resource collections, the right shift operator, >>,
can be used as an alias for the remove() method, as shown in the following
example:
>>> mygroup.users >> joe

__repr__()
This method is invoked implicitly by Jython when an expression entered in
interactive mode returns a resource object or when a resource object is passed
to the Jython repr() function. It returns a string representation of the resource
collection, as shown in the following example:

858

IBM Cloud Orchestrator 2.4.0.2: User's Guide

>>> deployer.ipgroups
[
{
"created": May 13, 2009 3:46:15
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 1:28:19
},
{
"created": May 14, 2009 2:13:59
"gateway": "192.168.0.1",
"id": 7,
"ips": (nested object),
"name": "192.168.0.0",
"netmask": "255.255.255.0",
"networks": (nested object),
"primarydns": "192.168.0.2",
"secondarydns": "192.168.0.3",
"subnetaddress": "192.168.0.0",
"updated": May 14, 2009 2:13:59
}
]

PM,

PM
PM,

PM

__str__()
Returns a string representation of the resource collection. The returned string is
readable, though it might be a lengthy string if the resource collection contains
many resources. This method is called implicitly when a resource collection is
printed, for example if a Jython expression entered in interactive mode returns
a resource collection as was seen in the earlier example. It can also be invoked
explicitly by passing a resource collection to the Jython str() function.
>>> print str(deployer.ipgroups)
[
{
"created": May 13, 2009 3:46:15
"gateway": "10.0.0.1",
"id": 2,
"ips": (nested object),
"name": "ten",
"netmask": "255.0.0.0",
"networks": (nested object),
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 14, 2009 1:28:19
},
{
"created": May 14, 2009 2:13:59
"gateway": "192.168.0.1",
"id": 7,
"ips": (nested object),
"name": "192.168.0.0",
"netmask": "255.255.255.0",
"networks": (nested object),
"primarydns": "192.168.0.2",
"secondarydns": "192.168.0.3",
"subnetaddress": "192.168.0.0",
"updated": May 14, 2009 2:13:59
}
]

PM,

PM
PM,

PM

Chapter 11. Reference

859

__unicode__()
Returns a Jython Unicode string containing a string representation of the
resource collection. This method is called implicitly when a resource collection
is passed to the Jython unicode() function or used in a context that requires a
Unicode string, as shown in the following example:
>>> unicode(deployer.ipgroups)

Related concepts:
Resources on the command line on page 843
Any IBM Cloud Orchestrator functional object is a resource object on the
command-line interface. Within the command-line interface, Jython objects are
used to represent these resources. The IBM Cloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
Related information:
Jython
Python documentation

Wizard objects on the command-line interface

The wizard object interactively prompts you for the set of information you must
enter to create a resource. The class is supported by the create() method of most
resource collections.

Usage
Use the wizard class as part of the create() method of a resource collection to
create a resource. The wizard class presents a series of prompts for information that
is used when creating a resource object.
The wizard object is supported by resource collection create methods as:
A temporary wizard object
>>> deployer.<resource_collection>.create(deployer.wizard)

A wizard object that you explicitly create

>>> w = deployer.wizard()
>>> deployer.<resource_collection>.create(w)

After you have entered the information requested by a prompt, click enter to
proceed to the next prompt. Prompts that are not required are indicated with the
inclusion of (optional) in the prompt. If you do not want to enter a value for an
optional prompt, click Enter to advance to the next prompt. For some other
prompts, a list of possible values can be accessed. The prompt for these fields
includes (* to select from list)". If you enter *, then a list of values is display. Enter
the number associated with the option you would like to select.
>>> w = deployer.wizard()
>>> deployer.virtualsystems.create(w)
Enter ?? for help using the wizard.
name: MyVirtualSystem
pattern (* to select from list): *
1. MyPattern1
2. MyPattern2
3. MyPattern3
pattern (* to select from list):1

860

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Help is available when using the wizard class

v Enter ?? for additional help on how to use the wizard
v Enter ? for additional help with a specific prompt. Additional information about
the information expected from this prompt is displayed.
v Enter ! to exit the wizard
Validation logic is used to ensure that a valid value has been entered. If the
entered value is not valid for a particular prompt, then an error is displayed and
you are then reprompted. After the last prompt has been completed, the resource is
created based on the information provided.

Examples
See the following example of the screen output when creating an user object using
the wizard class.
>>> w = deployer.wizard()
>>> deployer.users.create(w)
Enter ?? for help using the wizard.
username: joeuser
fullname: Joe User
password (optional):
email: [email protected]
{
"clouds": (nested object),
"currentmessage": "RM02013",
"currentmessage_text": "User has not logged in yet",
"currentstatus": "RM01062",
"currentstatus_text": "Inactive",
"email": "[email protected]",
"fullname": "Joe User",
"groups": (nested object),
"id": 2,
"parts": (nested object),
"password": (write-only),
"patterns": (nested object),
"roles": (nested object),
"scripts": (nested object),
"username": "joeuser",
"virtualimages": (nested object),
"virtualsystems": (nested object)
}

Methods
toDict
If a wizard object was explicitly constructed, use the toDict() method of the
wizard class to create a dictionary (dict) object with the required keys. The
following example shows how to use the toDict() method to create a dict
object as a continuation of the wizard example.
>>> w.toDict()
{fullname: uJoe User, email: [email protected], username: ujoeuser}

Related concepts:
Resource collections on the command line on page 847
IBM Cloud Orchestrator manages different types of resources, for example
hypervisors, patterns, virtual images, and virtual system instances. These resources
can be collected into groups of like objects called resource collections. Within the
command-line interface, Jython objects are used to represent these resource
collections.
Chapter 11. Reference

861

Resources on the command line on page 843

Any IBM Cloud Orchestrator functional object is a resource object on the
command-line interface. Within the command-line interface, Jython objects are
used to represent these resources. The IBM Cloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
Related information:
Jython
Python documentation

ACL object
You can use the access control list (ACL) object to set and control user access for
other IBM Cloud Orchestrator resources.

Purpose
Use the access control list (ACL) object to set and control user access for the
following objects:
AddOns For more information about Add-ons, see AddOn command-line interface
reference on page 740.
Clouds For more information about clouds, see Cloud group command-line
interface reference on page 745.
EnvironmentProfiles
For more information about environment profiles, see Environment
profiles on the command-line interface on page 749.
Hypervisors
For more information about hypervisors, see Hypervisor command-line
interface reference on page 758.
Patterns
For more information about patterns, see Virtual system patterns (classic)
command-line interface reference on page 818.
Scripts
For more information about scripts, see Script package command-line
interface reference on page 777.
Virtual images
For more information about virtual images, see Virtual images
command-line interface reference on page 792.
Virtual systems
For more information about virtual systems, see Virtual system instances
(classic) command-line interface reference on page 804.

ACL object
The ACL object represents the ACL associated with a IBM Cloud Orchestrator
resource. The IBM Cloud Orchestrator manages access to resources with a
hierarchical set of permissions. These permissions are represented by constants in
the IBM Cloud Orchestrator package. From the least access to greatest access, these
permissions are:
NO_PERMISSIONS
The user cannot access the resource.

862

IBM Cloud Orchestrator 2.4.0.2: User's Guide

READ_PERMISSION
The user can view the resource and use it in a read-only manner, but
cannot alter the resource.
UPDATE_PERMISSION
In addition to viewing and using the resource, the user is permitted to
alter the resource.
CREATE_PERMISSION
Typically applied to collections of resources, with this permission the user
can create new resources.
DELETE_PERMISSION, ALL_PERMISSION
The user is granted full access to the resource.
ACL objects are accessed using the ACL property of the resource to which they apply,
as shown in the following example:
>>> mypattern = deployer.patterns[0]
>>> mypattern.acl
{
(user cbadmin): all
}

ACL methods
The ACL object provides the following methods:
check(entity)
Queries the IBM Cloud Orchestrator to determine what permissions the
specified user has been granted to the resource associated with this ACL.
The following example shows this method:
>>> deployer.patterns[0].acl.check(deployer.self())

__contains__(item)
Indicates if a specific permission has been defined for the specified user, as
shown in the following example:
>>> deployer.users[user1] in deployer.virtualimages[0].acl

__delitem__(key)
Removes any explicit permissions set for the specified user for this
resource. This method is called implicitly by the Jython del statement, as
shown in the following example:
>>> user = deployer.users[user2][0]
>>> del deployer.patterns[0].acl[user]

__getitem__(key)
Returns the permission explicitly set for the specified user for this resource.
This method is started implicitly when a user is used as an index to an
ACL, as shown in the following example:
>>> deployer.virtualimages[0].acl[deployer.everyone()]

__iter__()
This method is started implicitly when you reference an ACL object in a
context that requires iterating over all the entries. This method is also
started implicitly when you are explicitly passing the ACL object to the
Jython iter() function. The following example shows this method:
>>> for userorgroup in myvirtualsystem.acl:
...
print userorgroup.name

Chapter 11. Reference

863

__len__()
Returns the number of permissions explicitly set for this resource, as
shown in the following example:
>>> len(deployer.scripts[0].acl)

refresh()
Refreshes the cached ACL entries with current data from the IBM Cloud
Orchestrator.
__repr__()
This method is started implicitly by Jython when an expression entered in
interactive mode returns an ACL or when an ACL is passed the Jython
repr() function. It returns a string representation of the resource. The
following example shows this method being implicitly started:
>>> deployer.scripts[0].acl

__setitem__(key, value)
Sets an explicit ACL for the specified user. This method is started implicitly
when you use the []= construct, as shown in the following example:
>>> myscript.acl[deployer.users[user2]] = deployer.READ_PERMISSION

The value specified inside the square brackets must be a User object. The
value to the right of the equal sign must be one of the following values:
v
v
v
v
v

deployer.NO_PERMISSIONS
deployer.READ_PERMISSION
deployer.UPDATE_PERMISSION
deployer.CREATE_PERMISSION
deployer.DELETE_PERMISSION

v deployer.ALL_PERMISSIONS
__str__()
Returns a string representation of this ACL. This method is started
implicitly by Jython when a resource object is used as a value in a string
formatting operation. This method is also started implicitly by Jython
when it is passed as a parameter to the Jython str() function. The
following example shows this method:
>>> print Here is the ACL: %s % deployer.patterns[0].acl
>>> str(deployer.patterns[1].acl)

__unicode__()
Returns a string representation of this ACL. This method is started
implicitly by Jython when a resource object is used as a value in a string
formatting operation. This method is also started implicitly when it is
passed as a parameter to the Jython unicode() function. The following
example shows this method:
>>> print Here is the ACL: %s % deployer.patterns[0].acl
>>> str(deployer.patterns[1].acl)

For more information about working with resource objects, see the Resources,
resource collections, and methods on page 842 section.
Related concepts:
Resources on the command line on page 843
Any IBM Cloud Orchestrator functional object is a resource object on the
command-line interface. Within the command-line interface, Jython objects are
used to represent these resources. The IBM Cloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,

864

IBM Cloud Orchestrator 2.4.0.2: User's Guide

virtual images, and virtual system instances.

Related information:
Jython
Python documentation

Additional command-line interface utilities

The IBM Cloud Orchestrator command-line interface includes a set of utilities that
can help you with various tasks you are performing.

Purpose
This topic provides a listing of utilities you can use with IBM Cloud Orchestrator
command-line interface to accomplish the following tasks:

deployer.admin get the administrative user

You can use the deployer.admin function as a convenience method to get the
administrative user. The deployer.admin function requires no argument and it
returns the user object for the administrative user in IBM Cloud Orchestrator. For
additional help on the user object returned, enter the following command:
>>> help(deployer.admin())

deployer.cliversion obtain the command-line interface version

You can use the deployer.cliversion function to determine the version of the
command-line interface code you are using, as shown in the following example:
>>> deployer.cliversion

This function returns an object with a string representation that is the version of
the command-line interface code, as shown in the following example:
1.0.0.0-11703

Note: This object is not a string, but can be converted to a string using the str()
command, as shown in the following example:
>>> if str(deployer.cliversion).startswith(1.0.0):
...
print running 1.0.0 deployer CLI
...
running 1.0.0 deployer CLI

deployer.everyone return the Everyone project

You can use the deployer.everyone function to return the Everyone project. The
deployer.everyone function takes no arguments and returns the Group object for
the Everyone project in IBM Cloud Orchestrator. For additional help on the Group
object returned, enter the following command:
>>> help(deployer.everyone())

deployer.exit exit the command-line interface

The deployer.exit function exits the command-line interface. In interactive mode,
you can use exit without the deployer prefix to end an interactive IBM Cloud
Orchestrator command-line interface session. In interactive mode, enter the
following command:
>>> exit
Chapter 11. Reference

865

In batch mode, enter the following command:

>>> deployer.exit

deployer.self obtain the current user

Use the deployer.self function to return a user object for the current user. The
deployer.self function takes no argument and returns the user object
corresponding to the user specified when the command-line interface was started.
For additional help on the user object returned, enter the following command:
>>> help(deployer.self())

deployer.version obtain the Workload Deployer component

version
You can use the following command to obtain the version of the Workload
Deployer component in IBM Cloud Orchestrator with which your command-line
interface session is communicating:
>>> deployer.version

This function returns the following object:

Workload Deployer Appliance at deployer.xyz.com, firmware version 1.0.0.0-11703

Note: This object is not a string but you can convert it to a string using str(), as
shown in the following example:
>>> if str(deployer.version).find(1.0.0) >= 0:
...
print deployer appliance is version 1.0.0
...
deployer appliance is version 1.0.0

deployer.waitFor order operation processing

You can use the waitFor function to specify the order of function processing. This
function is like resource.waitFor(), but it is not tied to a particular resource; it is a
generic utility function to periodically check a condition that you supply. The
deployer.waitFor function can assist you in writing scripts that must wait for the
IBM Cloud Orchestrator to complete a particular action. The deployer.waitFor
function periodically evaluates a particular expression until the expression
evaluates to a true value or a timeout expires. The function accepts the following
arguments:
condition
The condition to wait for. If o is an object that can be called, it is invoked
at the start of each interval to determine whether to continue waiting. A
true value causes this function to return, a false value causes the function
to continue waiting.
maxWait
The maximum wait time, expressed as a number of seconds. Floating point
values can be used to indicate fractions of a second. A negative value
causes this function to wait indefinitely. If a value is not supplied, the
default value is -1.
interval
The interval at which o is evaluated, expressed as a number of seconds.
Floating point values can be used to express fractions of a second. The
default value is 10 seconds.

866

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The deployer.waitFor returns the value obtained the last time the condition was
evaluated.
For more information about working with resource objects, see the Resources,
resource collections, and methods on page 842 section.
Related concepts:
Resources on the command line on page 843
Any IBM Cloud Orchestrator functional object is a resource object on the
command-line interface. Within the command-line interface, Jython objects are
used to represent these resources. The IBM Cloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
Related information:
Jython
Python documentation

REST API reference

The representational state transfer (REST) application programming interface (API)
is provided by IBM Cloud Orchestrator.

Before you begin

Each product exposes a REST API as there are no special configuration settings to
enable or disable this interface. The IBM Cloud Orchestrator REST API is available
on the same IP address or host name used to access the product GUI and
command-line interface. Unlike the GUI, the REST API is only supported over the
HTTPS protocol on port 443. The product uses a self-signed certificate for its SSL
sessions. The same certificate is used for GUI, command-line interface and REST
API sessions. You need to configure your HTTPS client to either accept or ignore
this certificate during the SSL handshake. You must use an HTTPS client that
allows you to set the HTTP headers for each request. This is because there are
multiple headers required for authentication, authorization, and content
negotiation.
To comply with stricter security requirements, IBM Cloud Orchestrator enforces the
use of the fully qualified domain name (FQDN) to call the user interfaces. You
must use the FQDN to implement single sign-on. The FQDN is also necessary for
all HTTP POST and PUT operations, which are used to submit all forms in the
user interface, including the login credentials. In emergency cases only: if the
FQDN cannot be used, you can disable the security check by removing the
cookie_domain entry from the /opt/ibm/ccs/scui/etc/config.json file on Central
Server 2.
When generating HTTP requests to the IBM Cloud Orchestrator REST API, pay
special attention to the following headers:
Accept
With a few exceptions, the REST API generates JSON-encoded data in its
responses. Include an "Accept: application/json" header in your request to
indicate the ability of your client to handle JSON responses.
Accept-Language
Use this header on your HTTP request to specify which language or locale

Chapter 11. Reference

867

should be used by the product when generating the response data. You can
specify any of the languages supported by the product.
Authentication
The REST API only supports HTTP basic authentication. After successfully
authenticating, the server will return two cookies named zsessionid and
SimpleToken that should be included with subsequent HTTP requests that
are part of the same session. The same user IDs and passwords used to
access the GUI and the command-line interface are used to access the REST
API. The authorization of a user to perform actions on the product is
independent of the interface (GUI, command-line interface or REST API)
used to request the actions.
Content-Type
All the content included in an HTTP request body sent to the product must
be JSON encoded. You must include a "Content-Type: application/json"
header to indicate this for each request that includes any data.
X-IBM-Workload-Deployer-API-Version: 4.0.0.1
Every HTTP request to the product must include a "X-IBM-WorkloadDeployer-API-Version: 4.0.0.1" header to indicate that your client expects the
REST API semantics described in this document.
domainName
When not using the default domain, the HTTP request must include in the
header "domainName:<yourDomainName>" to let the user be authenticated to
the <yourDomainName> domain.
projectName
When not using the default project, the HTTP request must include in the
header "projectName:<yourProjectName>" to let the user be authenticated
in the <yourProjectName> project.
The REST API is only supports the sending and receiving of UTF-8 encoded data.
Ensure that your HTTP client is appropriately set to encode and decode character
data, including JSON data. All responses of REST requests in JSON format are
encoded in UTF-8.
Note: Key-value pairs that are only used by user interface clients are optional.

REST API frameworks

This topic describes the REST API frameworks used in an IBM Cloud Orchestrator
environment for REST calls (client and server).
The following REST API frameworks are used:
v org.apache.wink 1.1.3: used by IBM Cloud Orchestrator.
v javax.net.ssl.HttpsURLConnection: used by the genericREST implemented by
IBM Cloud Orchestrator that makes REST calls from Business Process Manager
to IBM Cloud Orchestrator.
v org.apache.http: used by Business Process Manager to connect to OpenStack.
For customized REST calls that are implemented outside of IBM Cloud
Orchestrator, make sure that the compatible REST API framework is used. For
example, if you implement a script that makes REST calls against IBM Cloud
Orchestrator, you must use the org.apache.wink 1.1.3 framework or any other
compatible REST API framework.

868

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Orchestration actions REST API

You can use this set of REST API calls to interact with orchestration actions.

List all orchestration action entries

Use this REST API method to list all orchestration action entries.

Available HTTP method

Table 93. List all orchestration action entries REST API call
HTTP method

GET

URL pattern

https://hostname/resources/automation?parm1=value1
&parm2=value2...

Response

JSON array of all orchestration action entries filtered according to

the query parameters:
{ id:
name:
description:
created:
updated:
priority:
process:
process_app_id:
process_app_short_name:
process_app_name:
category:
operation_type:
ownerid:
apply_to_all_pattern:
event:
human_service:
human_service_app_id:
human_service_app_short_name:
human_service_app_name:
implementation_type:
icon:
}

Return values

v 200 - OK
v 401 - Unauthorized
v 404 - Not found

Structure of the query string:

v A parameter list is appended to the URL after the '?' mark.
v The query parameters are specified as parameter=value, where the parameters
and values are URL encoded.
v Multiple parameters are separated by an ampersand '&'.
v The following parameters can be included in the URL:
name
description
created
updated
process
category
operation_type
event
Chapter 11. Reference

869

 human_service
implementation_type

Retrieve an orchestration action entry

Use this REST API method to retrieve a particular orchestration action entry.

Available HTTP method

Table 94. Retrieve an orchestration action entry REST API call
HTTP method

GET

URL pattern

https://hostname/resources/automation/{id}

Response

JSON object for the specific orchestration action entry, based on the
ID provided in the query:
{ id:
name:
description:
created:
updated:
process:
process_app_id:
process_app_short_name:
process_app_name:
category:
operation_type:
apply_to_all_pattern:
event:
icon:
human_service:
human_service_app_id:
human_service_app_short_name:
human_service_app_name:
implementation_type:
ownerid:
pattern[
{
id,
patternId,
paternType
}
]
priority:
}

Return values

v 200 - OK
v 401 - Unauthorized
v 404 - Not found

Add or update an entry in the orchestration actions

Use this method to update one of your entries in the orchestration actions or to
add a new one.

Available HTTP method

Table 95. Add or update an entry in the orchestration actions REST API call

870

HTTP method

PUT

URL pattern

https://hostname/resources/automation/{id}

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 95. Add or update an entry in the orchestration actions REST API call (continued)
Response

JSON object for the updated orchestration action entry:

{ id:
name:
description:
process:
process_app_id:
process_app_short_name:
process_app_name:
category:
operation_type:
ownerid:
apply_to_all_pattern:
event:
human_service:
human_service_app_id:
human_service_app_short_name:
human_service_app_name:
implementation_type
pattern[
{
id,
patternId,
paternType
}
]
}

Return values

v 201 - Created and location (URL) of the updated orchestration

action entry
v 401 - Unauthorized
v 404 - Not found
v 415 - Unsupported media type (incorrect XML document sent)

Delete an orchestration action entry

Use this REST call to delete a selected entry from the orchestration actions.

Available HTTP method

Table 96. Delete an orchestration action entry REST API call
HTTP method

DELETE

URL pattern

https://hostname/resources/automation/{id}

Response

The specified entry is deleted from the orchestration actions.

Return values

v 204 - No content
v 401 - Unauthorized
v 404 - Not found

Chapter 11. Reference

871

Get entries for a specific virtual system

Use this REST call to retrieve information about orchestration action entries for a
virtual system with a specified ID.
Table 97. Get entries for a specific virtual system REST API call
HTTP method

GET

URL pattern

https://hostname/resources/instances/{id}/
automation?parm1=value1&parm2=value2...

Response

JSON array of all entries from the orchestration actions, filtered

according to the specified parameters:
{ id:
name:
description:
process:
category:
operation_type:
apply_to_all_pattern:
event:
human_service:
implementation_type
}

Return values

v 201 - Created and location (URL) of the updated automation

registry entry
v 401 - Unauthorized
v 404 - Not found
v 415 - Unsupported media type (incorrect XML document sent)

Structure of the query string:

v A parameter list is appended to the URL after the '?' mark.
v The query parameters are specified as argument=value, where the arguments
and values are URL encoded.
v Multiple parameters are separated by an ampersand &.
v The following parameters can be included in the URL:
name
description
process
category
operation_type
event
human_service
implementation_type

872

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Business Process Manager Invoker REST API

You can use this set of Invoker REST APIs to retrieve information about artifacts
that are available in Business Process Manager without accessing them directly.
For detailed information about Business Process Manager REST API, see the
Business Process Manager information center.

Retrieve available BPM Business Processes

Use these APIs to retrieve a list of all the BPM Business Processes that are available
for the implementation of self-service offerings or orchestration actions.
List all BPM Business Processes:
Use this REST call to retrieve a list of all the BPM Business Processes that are
available for the implementation of self-service offerings or orchestration actions.
Available HTTP method
Table 98. Get list of all BPM Business Processes
HTTP method

GET

URL pattern

https://hostname/kernel/bpm/runbook/

Response

A list of available BPM Business Processes is returned. If no BPM

Business Processes are available, an empty list is returned with
HTTP Code 200. The returned list has the following parameters:
{ id:
displayName:
processAppId:
}

Return values

v 200 - No available BPM Business Processes found

An entry has the following attributes:

v id - the unique ID of the BPM Business Process as used in the underlying
execution engine. Communication with the underlying engine, for example, to
start a BPM Business Process, is typically done by using this ID.
v displayName - a human-readable name of the BPM Business Processes, typically
used for display in the UI.
v processAppId - an identifier of a collection of BPM Business Processes to which
the Business Process belongs.
The example shows a response to the following request:
GET /kernel/bpm/runbook/
[
{
"id": "25.916d4552-9cf4-40c3-89fe-7f7bc43b2435",
"displayName": "Create Business Object Test"
"processAppId": "2066.5d35fbc5-6949-4971-8e06-83ca4c3cc760",
},
{
"id": "25.2951bb80-e9b2-457a-9097-4443886d1dd5",
"displayName":"SCO_Process"
"processAppId": "2066.5d35fbc5-6949-4971-8e06-83ca4c3cc760",
}
]

Chapter 11. Reference

873

Get entries for a specific BPM Business Process:

Use this REST call to retrieve information about a BPM Business Process with an
indicated ID.
Available HTTP method
Table 99. Get information about a specific BPM Business Process
HTTP method

GET

URL pattern

https://hostname/kernel/bpm/runbook/runbook_id

Response

The following parameters of the BPM Business Process are

retrieved:
{ id:
displayName:
processAppId:
}

Return values

v 404 - The BPM Business Process not found

This example shows the response to the following request GET

/kernel/bpm/runbook/25.916d4552-9cf4-40c3-89fe-7f7bc43b2435:
{
"id": "25.916d4552-9cf4-40c3-89fe-7f7bc43b2435",
"displayName": "Create Business Object Test"
"processAppId": "2066.5d35fbc5-6949-4971-8e06-83ca4c3cc760",
}

Retrieve available human services

Use these APIs to retrieve information about the human services that are available
for the implementation of self-service offerings and orchestration actions in IBM
Cloud Orchestrator.
List all human services:
Use this REST API to retrieve a list of all the human services that are available for
the implementation of self-service offerings and orchestration actions in IBM Cloud
Orchestrator.
Available HTTP method
Table 100. Get list of all human services
HTTP method

GET

URL pattern

https://hostname/kernel/bpm/humanService

Response

A list of available human services is returned. If no human services

are available, an empty list is returned with HTTP Code 200. The
returned list has the following parameters:
{ id:
displayName:
runUrl:
}

Return values

874

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v 200 - No available human services found

An entry has the following attributes:

v id - the unique ID of the human service as used in the underlying execution
engine.
v displayName - a human-readable name of the human service, which is typically
used for display in the UI.
v runUrl - the URL at which the human service can be started.
The following listing shows an example response that can be retrieved via the
REST API:
[
{
"id": "1.6b0f42d8-0d65-4073-83bd-a3c7cb046f32",
"displayName": "AddUserToVM",
"runUrl": "http://xvm192:9080/teamworks/executeServiceByName?
processApp=SCO_P1&serviceName=AddUserToVM"
},
{
"id": "1.10027723-6b52-46f8-9105-535c75a09970",
"displayName": "Show_Topology_Data",
"runUrl": "http://xvm192:9080/teamworks/executeServiceByName?
processApp=SCO_P1&serviceName=Show_Topology_Data"
}
]

.
Get entries for a specific human service:
Use this REST call to retrieve information about a human service with an indicated
ID.
Available HTTP method
Table 101. Get information about a specific human service
HTTP method

GET

URL pattern

https://hostname/kernel/bpm/humanService/
<human_service_id>

Response

The following parameters of the human service are retrieved:

{ id:
displayName:
processAppId:
}

Return values

v 404 - The human service not found

This example shows the response to the following request:

GET /kernel/bpm/humanService/1.6b0f42d8-0d65-4073-83bd-a3c7cb046f32
{
"id": "1.6b0f42d8-0d65-4073-83bd-a3c7cb046f32",
"displayName": "AddUserToVM",
"runUrl": "http://xvm192:9080/teamworks/executeServiceByName?
processApp=SCO_P1&serviceName=AddUserToVM" }

Chapter 11. Reference

875

Retrieve the Inbox

Use these APIs to retrieve information about the contents of the Inbox.
For detailed information about Business Process Manager task REST API, see the
Business Process Manager information center.
List all Inbox items:
Use this REST API to retrieve a list of all the items contained in the Inbox.
Available HTTP method
Table 102. Get list of all Inbox items
HTTP method

GET

URL pattern

https://hostname/kernel/bpm/task

Response

A list of Inbox items is returned. If Inbox is empty, an empty list is

returned with HTTP Code 200. The returned list has the following
parameters:
{
id:
assignedTo:
assignedToType:
displayName:
domain:
operationContextId:
project:
relatedTo:
requester:
serviceInstanceId:
taskDueDate
taskOverdue:
taskPriority:
taskStatus:
taskType:
time:
}

Return values

v 200 - No available pending human activities found

An entry has the following attributes:

v id - the unique ID of the pending human activity as used in the underlying
execution engine.
v assignedTo - the human-readable display name of the group or user to which
this request is assigned.
v assignedToType:
group - if the task is still unclaimed.
user - if the task is claimed.
v displayName - a human-readable name of the pending human activity, which is
typically used for display in the UI.
v domain - the domain of the user who requested this process.
v operationContextId - the ID of the operation context or request that is
associated to this inbox
v project - the project on behalf of which this process was requested.
v relatedTo - the name of the process to which the pending human activity
belongs.

876

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v requester - the requester of the process to which the pending activity belongs.
v serviceInstanceId- the ID of the associated virtual system instance, if the
approval is part of a triggered event or user action.
v taskDueDate - due date of the pending human activity.
v taskOverdue:
true - if the current date is later than the due date of the pending human
activity.
false - otherwise.
v taskPriority - the priority of the task as used in the underlying execution
engine.
v taskStatus - the status of the pending human activity as used in the underlying
execution engine.
v taskType - the type of human activity:
approval - for an approval request.
general - for a general human task.
v time - the time at which the process was triggered.
The following listing shows an example response with one pending task:
[
{
"relatedTo": "Sample_DeleteInstanceApproval",
"taskStatus": "Received",
"taskPriority": "Normal",
"taskOverdue": "true",
"id": "8",
"requester": "admin",
"taskDueDate": "2013-08-19T17:27:26Z",
"time": "2013-08-19T16:27:26Z",
"displayName": "Delete Instance Approval: Sample1",
"taskType": "approval",
"assignedToType": "group",
"operationContextId": "1007",
"domain": "Default",
"serviceInstanceId": null,
"assignedTo": "All Users",
"project": "admin"
}
]

.
Get entries for a specific Inbox item:
Use this REST call to retrieve information about an Inbox item with an indicated
ID
Available HTTP method
Table 103. Get information about a specific Inbox item
HTTP method

GET

URL pattern

https://hostname/kernel/bpm/task/<task id>

Chapter 11. Reference

877

Table 103. Get information about a specific Inbox item (continued)

Response

The following parameters of an Inbox item are retrieved:

{
overdue:
dueDate:
status:
priority:
id:
displayName:
requester:
time:
type:
assignedToType:
assignedTo:
operationContextId:
domain:
project:
serviceInstanceId:
parameters:[
{
"Operation Type":
"Operation Context ID":
"Virtual System Pattern ID"
"Virtual System Name"
"Virtual System ID"
}*
],
}

Return values

v 404 - The Inbox item not found

An entry has the following attributes:

v overdue:
true - if the current date is later than the due date of the pending human
activity.
false - otherwise.
v duedate - due date of the pending human activity.
v status - the status of the pending human activity as used in the underlying
execution engine.
v priority - the priority of the task as used in the underlying execution engine.
v id - the unique ID of the pending human activity as used in the underlying
execution engine.
v displayName - a human-readable name of the pending human activity, which is
typically used for display in the UI.
v requester - the requester of the process to which the pending activity belongs.
v time - the time at which the process was triggered.
v type - the type of human activity:
approval - for an approval request
general - for a general task
v assignedToType:
group - if the task is still unclaimed.
user - if the task is claimed.
v assignedTo - the human-readable display name of the group or user to which
this request is assigned.

878

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v operationContextId - the ID of the operation context or request that is

associated to this inbox
v domain - the domain of the user who requested this process.
v project - the project on behalf of which this process was requested.
v serviceInstanceId- the ID of the associated virtual system instance, if the
approval is part of a triggered event or user action.
v parameters - a name-value list that holds more information about the task.
Note: For a general task, the parameters array is typically empty because an
additional UI of the underlying process engine is provided which can be started
via a URL.
This example shows the response to a request :
{
"overdue": "true",
"dueDate": "2013-08-19T17:27:26Z",
"status": "Pending",
"priority": "Normal",
"type": "approval",
"id": "8",
"requester": "admin",
"time": "2013-08-19T16:27:26Z",
"displayName": "Delete Instance Approval: Sample1"
"assignedToType": "group",
"operationContextId": "1007",
"domain": "Default",
"serviceInstanceId": null,
"assignedTo": "All Users",
"project": "admin"
"parameters": [
{ "Operation Type": "Delete Instance" },
{ "Operation Context ID": "\/kernel\/tasks\/505dcc6d-7a97-4563-8f7b-6569ebc9e94c" },
{ "Virtual System Pattern ID": "\/resources\/patterns\/1" },
{ "Virtual System Name": "Sample1" },
{ "Virtual System ID": "\/resources\/virtualSystems\/2"}
],
}

Service instance REST API

You can use this set of REST API calls to interact with the service instance
resource.

Get entries for a specific service instance

Use this REST call to retrieve information about a specific service instance entry
with a specified deployment ID.

Available HTTP method

Table 104. Get entries for a specific service instance entry with a specified deployment ID
REST API call
HTTP method

GET

URL pattern

https://hostname/kernel/serviceInstance/{deployment-id}

Chapter 11. Reference

879

Table 104. Get entries for a specific service instance entry with a specified deployment ID
REST API call (continued)
Response

The response has the following parameters:

{
"metaData": {
"cloudGroup":
"creator":
"id":
"name"
"params":
"status":
"type":
"virtualApplicationId":
"virtualApplicationPatternId":
"virtualSystemId":
"virtualSystemPatternId": },
"roles": [
"services": [
"virtualMachines": [
{
"cloudGroup":
"disk":
"hostname":
"hypervisorid":
"id":
"memory":
"name":
"networkInterfaces": [
{
"hostname":
"ip":
"ipgroup":
}
]
"partname":
"runtimeId":
"virtualCpu":
}
]
}

Return values

v 200 - OK
v 404 - The service instance with the given ID does not exist
v 500 - Internal server error

An entry has the following attributes:

v metaData - an object that contains instance level information, for example the
name of the instance, its unique identifier, type, owner, and access information.
v virtualMachines - an array of objects that contains an object for each managed
virtual machine.
v roles - an array that contains an object for each role. A role is a middleware role
that a virtual machine plays among the different virtual machines in the
deployed virtual application pattern.
v services - an array that contains an object for each service. A service is a
managed entity other than a virtual machine or a role.
metaData has the following attributes:
v name - a string that is a human-readable name of the instance.

880

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v type - a string that is internal (non-localized). It has one of the following values:
SINGLE_IMAGE_DEPLOYMENT - for instances that are deployed through the Virtual
Images application.
TOPOLOGY - for instances that are deployed from a virtual system pattern.
APPLICATION - for instances that are deployed from a virtual application
pattern or shared service.
v status - a string that is internal (non-localized). In case of the TOPOLOGY or
SINGLE_IMAGE_DEPLOYMENT type, the same as for the virtual system state
machine. In case of other types, the same as for the virtual application state
machine.
v id - the URI to retrieve the most current version of the document.
v virtualSystemId - the URI to retrieve the virtual system if there is any that is
associated.
v virtualApplicationId - the URI to retrieve the virtual application instance if
there is any that is associated.
v virtualApplicationPatternId - the storehouse URI for the vApp pattern if there
is any that is associated.
v virtualSystemPatternId - the URI for the system pattern that is used to create if
there is any that is associated.
v creator - the ID of the user who initiated the deployment of the instance. This
id is a resource id like /resources/users/1 for vSys and single image
deployments, and a storehouse id like /storehouse/admin/users/u-0 in other
cases.
v cloudGroup - the cloud group to which the virtual application instance was
deployed. The field can be empty for virtual system pattern deployments, or
single image deployments.
v params - a JSON object that contains custom parameters that were provided by
extension writers.
virtualMachine has the following attributes:
v name - a string identifier of the virtual machine. Typically, it does not match the
primary host name of the virtual machine. The identifier is unique within a
service instance.
v id - a unique string identifier of the virtual machine that is relative to the service
instance base url.
v cloudGroup - the URI of the cloud group where the virtual machine is deployed.
v networkInterfaces - network interfaces of the virtual machine.
v hostname - the primary host name of the virtual machine. If there are multiple
network interfaces, the primary host name depends on the implementation.
v virtualCpu - the number of virtual central processing units that is the number of
central processing units that the guest operating system on this virtual machine
sees.
v memory - the amount of memory that the guest operating system sees. The unit
of measurement is mebibyte (1 MB = 1048576 bytes).
v disk - the size of the primary/root disk. The unit of measurement is mebibyte (1
MB = 1048576 bytes).
v imageId - the image that was used to create the virtual machine. The lifecycles of
the virtual machine and image are separate.
v partname - the name of the part in the associated virtual system pattern, from
which the virtual machine was instantiated.
Chapter 11. Reference

881

v runtimeId - the ID of the virtual machine on the hypervisor. The format of this
string depends on the hypervisor.
v params - the custom parameters that were provided by extension writers.
networkInterface has the following attributes:
v ip - the IPv4 address in dotted decimal notation or the IPv6 address.
v hostname - a host name that should resolve to the given IP through DNS.
v ipgroup - the URI of the IP group that the address was allocated from.
role has the following attributes:
v name - the name of the role.
v type - the type of the role.
v endpoints - an array that contains an object for each endpoint.
v params - a JSON object that contains custom parameters that were provided by
extension writers.
service has the following attributes:
v name - a human-readable string that identifies the service.
v type - either a java-style package identifier or a tosca node type.
v params - contain custom parameters that were provided by extension writers. See
the details below:
It is a free-form JSON object that holds additional parameters that are required
by extension developers. The JSON object has the following limitations:
There is no support for JSON arrays, which are converted to strings.
All non-string simple types are converted to string when they are stored.
You can read and edit these objects to add data that their extension requires in
the context of a service instance. You can retrieve the data later from a Business
Process Manager process or other extension. This storage is backed by the
storehouse metadata APIs.
endpoint has the following attributes:
v name - a human-readable string that identifies the endpoint.
v URI - The URI that the endpoint points to.
The following listing shows an example response that can be retrieved by the
request:
{
"metaData": {
"cloudGroup": "\/resources\/clouds\/1",
"creator": "\/resources\/users\/2",
"id": "\/kernel\/serviceInstance\/1",
"name": "Test",
"params": {
"Hello": "World"
},
"status": "RM01005",
"type": "TOPOLOGY",
"virtualApplicationId": "",
"virtualApplicationPatternId": "",
"virtualSystemId": "\/resources\/virtualSystems\/1",
"virtualSystemPatternId": "\/resources\/patterns\/1"
},
"roles": [
],

882

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"services": [
],
"virtualMachines": [
{
"cloudGroup": "\/resources\/clouds\/1",
"disk": 10240,
"hostname": "192-0-2-13.lightspeed.brhmal.sbcglobal.net",
"hypervisorid": "\/resources\/hypervisors\/PM-1",
"id": "1",
"memory": 2048,
"name": "965a92be-OS Node-Test-1",
"networkInterfaces": [
{
"hostname": "192-0-2-13.lightspeed.brhmal.sbcglobal.net",
"ip": "192.0.2.13",
"ipgroup": "\/resources\/ipgroups\/2"
}
],
"partname": "OS Node",
"runtimeId": "1b9417ca-6f66-42ec-a2da-661739d8e66d",
"virtualCpu": 1
}
]
}

Metadata parameters REST API

You can use this set of REST API calls to interact with metadata parameters.
Get parameters of specific metadata:
Use this REST call to retrieve information about metadata parameters of a specific
service instance.
Available HTTP method
Table 105. Get metadata parameters of a specific service instance REST API call
HTTP method

GET

URL pattern

https://hostname/kernel/serviceInstance/{deployment-id}/
metaData/params/attribute.member.member

Response

Returns the specified member of the object which is an attribute

within the parameters. Only the specified member of the object is
returned.

Return values

v 200 - OK
v 500 - Internal Server Error

Tip: To navigate within JSON objects, use . (dot).

The following listing shows an example response that can be retrieved via the
request:
{"Hello":"World"}

Chapter 11. Reference

883

Post metadata parameters:

Use this REST API call to post metadata parameters of a specific service instance.
Available HTTP method
Table 106. Post metadata parameters of a specific service instance REST API call
HTTP method

POST

URL pattern

https://hostname/kernel/serviceInstance/{deployment-id}/
metaData/params

Response

Updates parameters partially. Merges the posted attributes into the

existing parameters. Attributes that already exist are replaced with
the new values. New attributes are created.

Return values

v 200 - OK
v 500 - Internal Server Error

Note: For this rest call, you need a content-type: application/json header.
The following listing shows a sample request body:
{"Hello":"World"}

The following listing shows the response:

{"Status":"Ok"}

Delete parameters of specific metadata:

Use this REST API call to delete information about metadata parameters of a
specific service instance.
Available HTTP method
Table 107. Delete metadata parameters of a specific service instance REST API call
HTTP method

DELETE

URL pattern

https://hostname/kernel/serviceInstance/{deployment-id}/
metaData/params/attribute.member.member

Response

Deletes the specified member of the object that is an attribute

within the parameters. Only the specified member of the object is
deleted.
{"Status":"Ok"}

Return values

v 200 - OK
v 500 - No query parameter is specified, or internal server error

Note: The REST call always returns a {"Status":"Ok"} response on a 200 return
value.

884

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Virtual machines parameters REST API

You can use this set of REST API calls to interact with virtual machines
parameters.
Get parameters of a specific virtual machine:
Use this REST API call to retrieve information about virtual machine parameters of
a specific service instance.
Available HTTP method
Table 108. Get virtual machine parameters of a specific service instance REST API call
HTTP method

GET

URL pattern

https://hostname/kernel/serviceInstance/{deployment-id}/
virtualMachines/{name}/params/attribute.member.member

Response

Returns the specified member of the object which is an attribute

within the parameters. Only the specified member of the object is
returned.

Return values

v 200 - OK
v 500 - Internal Server Error

Tip: To navigate within JSON objects, use . (dot).

The following listing shows an example response that can be retrieved via the
request:
{"Hello":"World"}

Post virtual machine parameters:

Use this REST API call to post virtual machine parameters of a specific service
instance.
Available HTTP method
Table 109. Post virtual machine parameters of a specific service instance REST API call
HTTP method

POST

URL pattern

https://hostname/kernel/serviceInstance/{deploymentID}/
virtualMachines/{name}/params

Response

Updates parameters partially. Merges the posted attributes into the

existing parameters. Attributes that already exist are replaced with
the new values. New attributes are created.

Return values

v 200 - OK
v 500 - Internal Server Error

Note: For this rest call, you need a content-type: application/json header.
The following listing shows a sample request body:
{"Hello":"World"}

The following listing shows the response:

{"Status":"Ok"}

Chapter 11. Reference

885

Delete parameters of specific virtual machines:

Use this REST API call to delete information about virtual machines parameters of
a specific service instance.
Available HTTP method
Table 110. Delete virtual machines parameters of a specific service instance REST API call
HTTP method

DELETE

URL pattern

https://hostname/kernel/serviceInstance/{deploymentID}/
virtualMachines/{name}/params/attribute.member.member

Response

Deletes the specified member of the object that is an attribute

within the parameters. Only the specified member of the object is
deleted.
{"Status":"Ok"}

Return values

v 200 - OK
v 500 - No query parameter is specified, or internal server error

Note: The REST call always returns a {"Status":"Ok"} response on a 200 return
value.

Deployment parameters REST API

You can use this set of REST API calls to interact with deployment parameters of a
specific instance.

Get deployment parameters for a specific instance

Use this REST API call to retrieve information about deployment parameters for a
specific service instance.

Available HTTP method

Table 111. Get deployment parameters for a specific service instance REST API call
HTTP method

GET

URL pattern

http://hostname:port/resources/instances/{instanceid}/
deploymentparameters

Response

JSON object with the deployment parameters for the virtual system
instance filtered according to the query parameters:
{
parameterclass:
parametername:
parametervalue:
partkey:
userconfigurable:
scriptpackagename:
scriptpackagetype:
}

Return values

v 200 - OK
v 400 - Not Found
v 500 - Unexpected Error

Note: Instanceid is a virtual system ID (integer value).

886

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Deployment parameters have following attributes:

v parameterclass - string, parameter class as defined by the underlying pattern
model.
v partkey - string, label of the related virtual system part for the parameter.
v parametername - string, the name of the parameter.
v parametervalue - string, the value of the parameter.
v userconfigurable - boolean, specifies whether parametervalue can be updated.
Note: The combination of parameterclass, partkey and parametername is unique
within a virtual system instance.
Deployment parameters of script packages have two additional attributes:
v scriptpackagename - string, the name of a script package.
v scriptpackagetype - string, the type of a script package
The attribute scriptpackagetype has two values:
v APPLICATION for custom script packages.
v ADDON_<type> for add-ons.

Post deployment parameters for a specific instance

Use this REST API call to post information about deployment parameters for a
specific service instance.

Available HTTP method

Table 112. Post deployment parameters for a specific service instance REST API call
HTTP method

POST

URL pattern

http://hostname:port/resources/instances/{instanceid}/
deploymentparameters

Response

JSON object with the deployment parameters for the virtual system
instance that is filtered according to the query parameters:
{
parametername:
parametervalue:
partkey:
}

Return values

v 200 - OK
v 400 - Not Found
v 500 - Unexpected Error

Note: {instanceid} is a virtual system ID (integer value).

For the method to be successful, the following conditions must be met:
v The deployment parameter is known in the pattern.
v The deployment parameter is user-configurable.
v The call must be made before provisioning.
Deployment parameters have following attributes:
v partkey - string, label of the related virtual system part for the parameter.
v parametername - string, the name of the parameter.
v parametervalue - string, the value of the parameter.
Chapter 11. Reference

887

Note: The combination of parameterclass, partkey and parametername is unique

within a virtual system instance.

Core Services REST API

Core Services REST API overview
IBM Cloud Orchestrator uses REST APIs to allow easy, lightweight communication
between components and integration with external systems.

Linked Resources vs. Collection Resources

REST API implements a linked data concept where relations between resources are
provided with the response as meta-data. A linked resource is the most basic entity
in a response. It represents a resource itself as well as any links to other resources.
The following code is a structure of a linked resource:
{
"href": "https://host:9443/orchestrator/v2/...",
"item": { ... },
"link_1": {
"href": "https://host:9443/orchestrator/v2/..."
},
"link_2": {
"href": "https://host:9443/orchestrator/v2/..."
}
}

Each linked resource has at least one link to itself, the first href property. An item
property follows with the actual resource representation. There can also be
additional links to other resources. A collection resource is a collection of linked
resources. In addition to the basic properties of a linked resource, a collection
resource also features specific properties for pagination. The following code
displays the structure of a collection resource:
{
"href": "https://host:9443/orchestrator/v2/collection",
"start": 10,
"limit": 10,
"total": 49,
"first": {
"href": "https://host:9443/orchestrator/v2/collection/?_limit=10&_start=0"
},
"previous": {
"href": "https://host:9443/orchestrator/v2/collection/?_limit=10&_start=0"
},
"next": {
"href": "https://host:9443/orchestrator/v2/collection/?_limit=10&_start=20"
},
"last": {
"href": "https://host:9443/orchestrator/v2/collection/?_limit=10&_start=39"
},
"items": [ ... ]

The start, limit and total properties enable you to display the correct number of
pages in a UI. The number of pages is the total size divided by the page size. You
can also choose to leverage the provided first, next, etc. links and can call them
directly from a UI to navigate the collection easily.

888

IBM Cloud Orchestrator 2.4.0.2: User's Guide

HTTP Status Codes

The following codes apply:
Table 113.
Status Code

Request

Description

200 OK

GET /resource, GET

/collection, PUT /resource

General status if the request

went OK, no resources were
created.

201 Created

POST /collection

New resource was created.

202 Accepted

POST /collection/{id}/
launch

A launch request was

accepted.

204 No Content

DELETE /resource

A resource was deleted.

400 Bad Request

PUT /resource, POST

/collection

Request payload was not

complete or badly formatted.

401 Unauthorized

Any

Session has expired or no

SimpleToken was provided.

403 Forbidden

Any

Session is valid but user was

not authorized for the
requested operation.

404 Not Found

Any

Requested resource path was

not found.

405 Method Not Allowed

PUT /collection, DELETE

/collection

Tried to update or delete a

collection resource.

406 Not Acceptable

Any

Invalid Accept header. Only

application/json is allowed
by default.

409 Conflict

POST /collection

A resource with the same

identifier already exists.

415 Unsupported Media

Type

POST /collection, PUT

/resource

Requested invalid content

type. Only application/json
is allowed by default.

500 Internal Server Error

Any

An internal error occurred.

Log files should be checked.
The REST API may provide
additional hints in the
response body.

HTTP Media Types

By default, all REST APIs consume and produce application/json as their media
type. Other types such as text/xml are not supported unless stated otherwise.

Pagination, Filtering, Sorting and Searching

URL parameters used to control the output of a REST API are generally prefixed
with an underscore _ to distinguish them from queries on resource properties. This
avoids confusion between
/apples?sort=goldendelicious (gives all apples of the "goldendelicious" sort)
and
Chapter 11. Reference

889

/apples?sort=ascending&sortby=id (sorts apples by id in ascending order).

The following table describes URL keywords controlling REST API behavior:
Table 114.
Keyword

Meaning

_start=n

Start pagination at element n.

_limit=n

Set page size to n elements per page. There

is an upper boundary of 100 items and a
lower boundary of 5 items. If omitted, 10 is
the default.

_sortby=abc

Sort result set by resource attribute abc. If

omitted, id (or the respective identifier of
the resource) is the default.

_sort=asc | desc

Sort in ascending or descending order. If

omitted, asc is the default.

_search=abc

Do a case-insensitive, full-text search for abc

in the searchable parts of a resource.
Depends on REST API implementation,
usually name and description are searchable.

property=value

If no underscore prefix was given, filter for

resources with properties containing value.
Multiple values can be passed as a separate
property=value pair.

Examples
v /orchestrator/v2/categories - Returns service catalog categories starting at
index 0 with a limit of 10, sorted by ID in ascending order.
v /orchestrator/v2/categories?_start=10 - Returns service catalog categories
starting at index 10 with a limit of 10, sorted by ID in ascending order.
v /orchestrator/v2/categories?_start=10&_limit=20 - Returns service catalog
categories starting at index 10 with a limit of 20, sorted by IDin ascending order.
v /orchestrator/v2/categories?_sortby=name - Returns service catalog categories
starting at index 0 with a limit of 10, sorted by name in ascending order.
v /orchestrator/v2/categories?_sortby=id&_search=virtual - Returns service
catalog categories containing the word "virtual" starting at index 0 with a limit
of 10, sorted by ID in ascending order.
v /orchestrator/v2/categories?name=OpenStack - Returns service catalog
categories whose name is "OpenStack" starting at index 0 with a limit of 10.
v /orchestrator/v2/categories?id=123&id=456 - Returns service catalog categories
with the ids 123 and 456 starting at index 0 with a limit of 10.

890

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Offering REST API V2

The following topics cover categories, offering attributes and offering instances of
the offering REST API V2.
Categories:
Json Formats
Category Request:
{
"isbuiltin": 0,
"icon": "Web Machine Category Icon:ge100_webcatalog_24",
"name": "Manage Virtual Machines",
"description": "Deploy, start, stop and virtual machines based on a single image."
}

Category Response:
{
"href": "https://host:9443/orchestrator/v2/categories/4711",
"item": {
"id": 4711,
"isbuiltin": 0,
"icon": "Web Machine Category Icon:ge100_webcatalog_24",
"name": "Manage Virtual Machines",
"description": "Deploy, start, stop and virtual machines based on a single image."
}
}

Categories Response
{
"href": "https://host:9443/orchestrator/v2/categories/",
"start": 0,
"limit": 10,
"total": 9,
"first": {
"href": "https://host:9443/orchestrator/v2/categories/?_limit=10&_start=0"
},
"previous": null,
"next": null,
"last": {
"href": "https://host:9443/orchestrator/v2/categories/?_limit=10&_start=0"
},
"items": [ Category Response, ...., Category Response ]
}
Table 115.
Attribute

Description

Type

Mandatory

Generated

Comment

id

category id

Number

no

yes

automatically
assigned when a
new category gets
created

icon

icon name

String

no

no

name of the icon

that is displayed
with the category
in the UI

Chapter 11. Reference

891

Table 115. (continued)

Attribute

Description

Type

Mandatory

Generated

Comment

name

category name

String

yes

no

name of the
category

description

category
description

String

yes

no

description of the
category

isbuiltin

built in

Number

no

GET: Lists offering categories

URL pattern
/orchestrator/v2/categories
Accepts
*
Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
401 unauthorized
500 internal server error
Response
Categories Response
Search Attributes
name, description
Filter Attributes
all
Authorization
no authorization needed
POST: Creates a offering category
URL pattern
/orchestrator/v2/categories
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
201 created
Error Response Codes
400 bad request if bad JSON was passed or mandatory attributes were
missing
401 unauthorized
500 internal server error
Request
Category Request

892

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Response
Category Response
Authorization
role:"admin"
GET: Get category
URL pattern
/orchestrator/v2/categories/{id}
Accepts
*
Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Response
Category Response
Authorization
no authorization
PUT: Update category
URL pattern
/orchestrator/v2/categories/{id}
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
400 bad request if bad JSON was passed
401 unauthorized
404 not found
500 internal server error
Request
{
...
"name": "Manage Virtual Image",
"description": "Deploy, start, stop"
...
}

Chapter 11. Reference

893

Response
Category Response
Authorization
role: "admin"
DELETE: Delete category
URL pattern
/orchestrator/v2/categories/{id}
Accepts
*
Normal Response Codes
204 no content
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Authorization
role: "admin"
Offering attributes:
Attributes for the offering are displayed in this section.
Attributes
Table 116.
Attribute

Description

Type

Mandatory

Generated

Comment

id

service id

Number

no

yes

automatically assigned
when a new offering is
created

icon

icon name

String

no

no

name of the icon that is

displayed with the
category in the UI

name

offering name

String

yes

no

name of the offering

description

offering description

String

yes

no

description of the
offering

category

offering

Number

no

no

category id of this
offering

implementation_type

type of process that gets String

started

no

process_app_id

BPM process app id

containing the linked
process (process
attribute)

String

yes

no

process

BPM process
implementing the
offering or action

String

yes

no

894

IBM Cloud Orchestrator 2.4.0.2: User's Guide

defaults to
"ibm_bpm_process" if
not passed

Table 116. (continued)

Attribute

Description

Type

Mandatory

Generated

human_service_app_id

BPM process app id

containing the linked
human service
(human_service
attribute)

String

no

no

human_service

Human service
implementing the User
Interface for the
offering or action

String

no

no

Comment

ownerid

no

operation_type

no

"offering",
"singleInstanceAction",
"multiInstanceAction"

instancetype

type of instances the

process is working on

String

no

no

name of instance
provider

tags

List of service designer

tags matching to the
ones of the instance
type

List of
Strings

no

no

subset of tags of
instance provider

acl

Access control list

List of ACL no
JSON

no

acl/domain

no

acl/project
acl/role
acl/use
acl/modify
acl/view

Offering instances:
A list of instances for the offering are described in this section.
Instances
GET: Lists offerings
URL pattern
/orchestrator/v2/offerings
Accepts
*
Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
401 unauthorized
500 internal server error
Chapter 11. Reference

895

Response
Offerings Response
Search Attributes
name, description
Filter Attributes
id, name, description, icon, human_service, human_service_app_id,
priority, created, updated, process, process_app_id, owner_id, category,
implementation_type, operation_type, instancetype
Authorization
role: admin or ACL with 'view' set to 'true' for given domain, project and
role
POST: Creates an offering
URL pattern
/orchestrator/v2/offerings
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
201 created
Error Response Codes
400 bad request if bad JSON was passed or mandatory attributes were
missing
401 unauthorized
500 internal server error
Request
Offering Request
Response
Offering Response
Authorization
roles: "admin", "domain_admin"
POST: Creates an offering
URL pattern
/orchestrator/v2/offerings
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
201 created
Error Response Codes
400 bad request if bad JSON was passed or mandatory attributes were
missing
401 unauthorized

896

IBM Cloud Orchestrator 2.4.0.2: User's Guide

500 internal server error

Request
Offering Request
Response
Offering Response
Authorization
roles: "admin", "domain_admin"
GET: Get an offering
URL pattern
/orchestrator/v2/offerings/{id}
Accepts
*
Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Response
Offering Response
Authorization
role: admin or ACL with 'view' set to 'true' for given domain, project and
role
PUT: Update an offering
URL pattern
/orchestrator/v2/offerings/{id}
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
400 bad request if bad JSON was passed
401 unauthorized
404 not found
500 internal server error
Request
Offering Request (partial)
Response
Offering Response
Chapter 11. Reference

897

Authorization
role: admin or ACL with 'modify' set to 'true' for given domain, project and
role
DELETE: Delete an offering
URL pattern
/orchestrator/v2/offerings/{id}
Accepts
*
Normal Response Codes
204 no content
Error Response Codes
401 unauthorized
500 internal server error
Authorization
role: admin or ACL with 'modify' set to 'true' for given domain, project and
role
POST: Execute an offering
URL pattern
/orchestrator/v2/offerings/{id}/launch
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
202 accepted
Error Response Codes
400 bad request if bad JSON was passed
401 unauthorized
404 not found
500 internal server error
Request
Go to Launching an offering via offering API
Response
TaskResponse
Authorization
role: admin or ACL with 'use' set to 'true' for given domain, project and
role
GET: Get ACL entries for a given offering
URL pattern
/orchestrator/v2/offerings/{id}/acl
Accepts
*

898

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Response
ACLs Response
Authorization
no authorization needed but result is restricted for the given domain,
project and role of the user
PUT: Update given acl for a given offering
URL pattern
/orchestrator/v2/offerings/{id}/acl
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
400 bad request of bas JSON was passed
401 unauthorized
404 not found
500 internal server error
Request
ACLs Request
Response
ACLS Response
Authorization
no authorization needed but the given ACL is adjusted to the given
domain, project and role of the user
GET: Get input parameters for a given offering
URL pattern
/orchestrator/v2/offerings/{id}/parameters
Accepts
*
Content-Type
application/JSON
Normal Response Codes
200 OK
Chapter 11. Reference

899

Error Response Codes

401 unauthorized
404 not found
500 internal server error
Response
Parameters Response
Authorization
no authorization needed but result is restricted for the given domain,
project and role of the user
GET: Get graphical representation of a given offering workflow
URL pattern
/orchestrator/v2/offerings/{id}/graph
Accepts
*
Content-Type
application/JSON
Normal Response Codes
200 OK
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Response
image/jpeg binary image representing this offering's workflow
Authorization
no authorization needed but result is restricted for the given domain,
project and role of the user
Launching an offering via Offering REST API:
There are two ways of launching an offering. In both cases you need to know the
offering id of the offering to launch. You can either use the user interface or pass
the data directly with the initial request.
An offering can be retrieved by listing the offerings using a GET request on the
offerings:
GET https://<IBM_Cloud_Orchestrator>:8443/orchestrator/v2/offerings

The id attribute on each offering contains the offering id.

1. The offering does not require any input data In this case you can start the
offering by performing a POST request on the offering you want to launch.
POST https://<IBM_Cloud_Orchestrator>:8443/orchestrator/v2/offerings/<offering-id>/launch

2. The offering does require additional input data In this case you have to decide
whether you want to use the IBM Cloud Orchestrator User Interface to gather
that data and start the process, or if you provide the data as part of the launch
request.
Using the User Interface

900

IBM Cloud Orchestrator 2.4.0.2: User's Guide

If you want to use the IBM Cloud Orchestrator User Interface you will have to
perform two steps:
1. Issue the call to initiate the offering by performing the post request:
POST https://<IBM_Cloud_Orchestrator>:8443/orchestrator/v2/offerings/<offering-id>/launch

2. In the JSON response of that request find the redirect attribute that contains
the path to launch the IBM Cloud Orchestrator User Interface for the offering.
It looks like this: "redirect":"\/teamworks\/
executeServiceByName?processApp=SCONOVA
&serviceName=Deploy+Single+Virtual+Machine
&tw.local.operationContextId=3059"
3. Launch the URL:
https://<IBM_Cloud_Orchestrator>:8443/orchestrator/v2/offerings/<offering-id>/launch

After the data is filled in the offering will start automatically.

Pass the data directly with the initial request
Offerings started this way cannot have a human service configured. If the offering
has a human service configured, create a new one using the same process as the
original offering, with no human service configured. Creating such an offering can
be done in the IBM Cloud Orchestrator Self-Service Configuration User Interface.
To start the offering you must do the same POST request as in the other option for
creating an offering:
POST https://<IBM_Cloud_Orchestrator>:8443/orchestrator/v2/offerings/<offering-id>/launch

You must also provide a POST body in that request describing the
InputParameterObject that is passed into the process. Pass the body a JSON
document in this format:
{"parm":{"OperationParameter":
"<variable type=\"Sample_BusinessObject\">
<field1 type=\"String\"><![CDATA[Hello]]><\/field1>
<field2 type=\"String\"><![CDATA[Phone]]><\/field2> <\/variable>"}}

The OperationParameter is the serialized form of the related Business Process

Manager business object as returned by the Business Process
Managertw.system.serializer.toXML(tw.local.inputParameterObject)
The following methods are some ways of finding out more about the input
parameter datatype of the process you want to launch. If you need to inspect
parameters of the offering workflow, the following methods can be performed:
1. Use REST interface for IBM Cloud Orchestrator to retrieve details of a
registered offering:
GET https://<IBM_Cloud_Orchestrator>:8443/orchestrator/v2/offerings/<offering-id>

In this data you can find:

process
The name of theBusiness Process Manager process bound to the
offering.
process_app_id
The ID of the Business Process Manager application in which the
process is defined.
For details, refer to GET entries for a specific self-service offering.
Chapter 11. Reference

901

2. Use REST Interface for Business Process Manager - related resources to get
details about exposed items:
GET https://<IBM_Cloud_Orchestrator>:8443/rest/bpm/wle/v1/exposed

Find the process with display=process and processAppID=process_app_id.

{"status":"200", "data":{ "exposedItemsList":[ { "type":"process",
"itemID":"25.8403dd37-e049-46f5-8952-b7a46f0d198f",
"processAppID":"2066.931b0053-02bd-4f47-ac72-4eb527457383",
"snapshotID":"2064.73dd1d1a-b533-46ef-ba79-c94cb3b0de87",
"snapshotName":"version 2.8.1",
"display":"HR Open New Position", "ID":"2015.204" }

For more information, see http://www.ibm.com/support/knowledgecenter/

SSFTDH_8.5.0/com.ibm.wbpm.ref.doc/rest/bpmrest/
rest_bpm_wle_v1_exposed.htm.
3. Use REST Interface for Business Process Manager-related resources to get
details about the process model:
GET https://<IBM_Cloud_Orchestrator>:8443/rest/bpm/wle/v1/processModel/
{bpdId}?processAppId={string}&parts=dataModel

Use parts=all for more information about the process. Find the process with
itemID=process and processAppID=process_app_id:
{ "status":"200", "data":{ ..., "DataModel":{ ...} } }

For more information, see http://www.ibm.com/support/knowledgecenter/

SSFTDH_8.5.0/com.ibm.wbpm.ref.doc/rest/bpmrest/
rest_bpm_wle_v1_processmodel_bpdid_get.htm.
Sample Output:
Getting the type of the inputParameterObject. Getting the type detailed
information, here the parameters to that service are two string parameters named
field1 and field2.
{

"status" : "200",
"data" : {
"DataModel" : {
"properties" : { "message" : { "type" : "String", "isList" : false },
"returnFromRest" : { "type" : "String", "isList" : false }
},
"inputs" : {
"operationContext" : { "type" : "OperationContext", "isList" : false },
"inputParameterObject" : { "type" : "Sample_BusinessObject", "isList" : false }
},
...
"Sample_BusinessObject" : {
"properties" : { "field1" : { "isList" : false, "type" : "String },
"field2" : { "isList" : false, "type" : "String }
},
type" : "object",
"ID" : "12.2c079fa7-89a0-426c-a3c1-079be08930ac",
"isShared" : false
},

Getting an example for the input parameter payload

To get an example of the input parameter payload, trigger a request through the
IBM Cloud Orchestrator and query the input parameters of the request. It could
either be still running or finished. You must:
v Retrieve the request ID.

902

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Retrieve the input parameters for that request.

1. To get the request ID, select the triggered request in REQUEST HISTORY and
note the request ID as listed in the address bar.
2. Using the REST call to retrieve details about the request, use:
GET https://<IBM_Cloud_Orchestrator>:8443/kernel/tasks/{request-id}

3. Within the response, search for Operation Parameter. The following is a sample
excerpt:
"OperationParameter" : "<variable type=\"MyRequest\"
<vpmoNumber type=\"Integer\"><![CDATA[116560]]><\/vpmoNumber>
<appId type=\"Integer\"><![CDATA[19073]]><\/appId>
<attuidNo type=\"String\"><![CDATA[dw945f]]><\/attuidNo>
<serverType type=\"NameValuePair\">
<name type=\"String\"><![CDATA[Test]]<\/name>
<value type=\"String\"><![CDATA[T]]&gt;<\/value>
<\/serverType>

Getting information on a request

Once a request is started the IBM Cloud Orchestrator system can be queried for
the actual status of that request. This is done using the REST call:
GET https://<IBM_Cloud_Orchestrator>:8443/kernel/tasks/{id}

The response contains information about the status of the request. For details on
possible values, refer to GET entries for a specific task. Sample response (excerpt)
from
REST GET https://<IBM_Cloud_Orchestrator>:8443/kernel/tasks/{id}

:
{
"updated_iso" : "2014-02-19T17:54:15+0100",
"description_message" : "PROCESS_COMPLETE",
"domain" : "Default",
"created" : 1392828461580,
"error" : { ... },
"serviceInstance" : {
"virtualMachines" : [{
"memory" : 4096,
"hypervisorid" : "\/resources\/hypervisors\/PM-1",
"hostname" : "SC-192-168-0-103.RegionOne.example.com",
....
}
],
....
},
"user" : "admin",
"parm" : {
"startPlanByPlugpointEventHandler" : "done",
"CUSTOM_PARM1": "abc",
"CUSTOM_PARM2": "xyz",
"OperationParameter" : "<variable ...<\/variable>",
"serviceInstanceId" : "282",
"plan" : { ... },
"processId" : "1356"
},
"created_iso" : "2014-02-19T17:47:41+0100",
"status_localized" : "TASKSTATUS_COMPLETED",
"error_message" : "BPM_PROCESS_COMPLETE",
"status" : "COMPLETED",
"eventTopic" : "com\/ibm\/orchestrator\/serviceinstance\/plan\/ibm_bpm_process",
"delayInSeconds" : 30,

Chapter 11. Reference

903

"project" : "admin",
...
}
}

Resource instances REST API

Instances returned for a specific type are collected using an instance provider. An
instance provider is a Java class that can talk to a back-end to query instance
information such as VMs, disks, users, networks and other cloud resources.

JSON Formats
Resource Type Request
{
"name" : "myprovider",
"displayname" : "My Provider",
"description" : "This is my provider",
"icon" : "Web Icon:glyphicons_266_flag",
"provider" : "com.ibm.orchestrator.core.instance.providers.myprovider.MyProvider",
"type" : "admin",
"tags" : ["enabled", "disabled"],
"detailsview" : {
"application" : "SCOABC",
"humanservice" : "Show My Provider Details"
},
"keyfields" : [{
"instanceattribute" : "displayname",
"header" : "Name"
}, {
"instanceattribute" : "description",
"header" : "Description"
}
]
}

Resource Type Response

{
"name" : "myprovider",
"displayname" : "My Provider",
"description" : "This is my provider",
"icon" : "Web Icon:glyphicons_266_flag",
"provider" : "com.ibm.orchestrator.core.instance.providers.myprovider.MyProvider",
"type" : "admin",
"tags" : ["enabled", "disabled"],
"detailsview" : {
"application" : "SCOABC",
"humanservice" : "Show My Provider Details"
},
"keyfields" : [{
"instanceattribute" : "displayname",
"header" : "Name"
}, {
"instanceattribute" : "description",
"header" : "Description"
}
]
}

Resource Types Response

{
"href": "http://<hostname:port>/orchestrator/v2/instancetypes",
"start": 0,
"limit": 10,

904

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"total": 3,
"first": "http://<hostname:port>/orchestrator/v2/instancetypes?_start=0&_limit=10",
"previous": null,
"next": null,
"last": "http://<hostname:port>/orchestrator/v2/instancetypes?_start=0&_limit=10",
"items":
[
Resource Type Response 1,...,Resource Type Response n
]
}

Resource Instance Request

{
"parm":
{
.... Instance type dependent paramter JSON object ....
},
"displayname": "mhtest1",
"detailsURL": "<hostname:port>/teamworks/executeServiceByName?processApp=<FOO>
&;serviceName=Show+Server+Details&tw.local.serverId
=b479108c-df8f-4462-be8b-f80af4a59d15&tw.local
.region=RegionOne&tw.local.user=<user>&tw.local.
domain=Default&tw.local.project=<project>",
"status": "ACTIVE",
"region": "RegionOne",
"icon": "Server Category Icon:ge100_servercatalog_24",
"openstackId": "b479108c-df8f-4462-be8b-f80af4a59d15",
"tags":
[
"active"
],
"id": "RegionOne--b479108c-df8f-4462-be8b-f80af4a59d15",
"updated": "2014-03-31T11:04:58Z",
"ipAddresses": "vmnet: 10.0.0.100",
"description": "mhtest1"
}

Resource Instance Response

{
"href": "<hostname:port>/orchestrator/v2/instancetypes/openstackvms
/instances/RegionOne--b479108c-df8f-4462-be8b-f80af4a59d15",
"created": "2014-03-31T11:04:18Z",
"parm":
{
.... Instance type dependent paramter JSON object ....
},
"displayname": "mhtest1",
"detailsURL": "<hostname:port>/teamworks/executeServiceByName?
processApp=<FOO>&serviceName=Show+Server+Details&tw
.local.serverId=b479108c-df8f-4462-be8b-f80af4a59d15&tw
.local.region=RegionOne&tw.local.user=<user>&tw
.local.domain=Default&tw.local.project=<project>",
"status": "ACTIVE",
"region": "RegionOne",
"icon": "Server Category Icon:ge100_servercatalog_24",
"openstackId": "b479108c-df8f-4462-be8b-f80af4a59d15",
"tags":
[
"active"
],
"id": "RegionOne--b479108c-df8f-4462-be8b-f80af4a59d15",
"updated": "2014-03-31T11:04:58Z",
"ipAddresses": "vmnet: 10.0.0.100",
"description": "mhtest1"
}
Chapter 11. Reference

905

Resource Instances Response

{
"href": "<hostname:port>/orchestrator/v2/instancetypes/openstackvms/instances",
"start": 0,
"limit": 10,
"total": 2,
"first": "<hostname:port>/orchestrator/v2/instancetypes/
openstackvms/instances?_start=0&amp;_limit=10",
"previous": null,
"next": null,
"last": "<hostname:port>/orchestrator/v2/instancetypes
/openstackvms/instances?_start=0&amp;_limit=10",
"items":
[
Resource Instance Response 1, ..., Resource Instance Response n
]
}

Instances
GET : Lists all resource types
URL pattern
/orchestrator/v2/instancetypes
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
500 internal server error
Response
Resource Type Response
Authorization
No authorization needed
POST: Create resource type
URL pattern
/orchestrator/v2/instancetypes/
Accepts
application/JSON
Content type
application/JSON
Normal Response Codes
201
Error Response Codes
401 unauthorized
409 conflict
500 internal server error

906

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Request
Resource Type Request
Response
Resource Type Request
Authorization
role: admin
GET: Get one resource type
URL pattern
/orchestrator/v2/instancetypes/{name}
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
404 not found
500 internal server error
Response
Resource Type Response
Authorization
No authorization needed
PUT: Update a resource type
URL pattern
/orchestrator/v2/instancetypes/{name}
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Request
Resource Type Request (partial)
Response
Resource Type Response
Authorization
role: admin
DELETE: Delete a resource type.

Chapter 11. Reference

907

URL pattern
/orchestrator/v2/instancetypes/{name}
accepts
*/*
Content-Type
application/JSON
Normal Response Codes
204
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Authorization
role: admin
GET : List instances of a given type.
URL pattern
/orchestrator/v2/instancetypes/{name}/instances
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Response
Resource Instances Response
Authorization
Instance provider dependent. Generic Provider: Access Control Link with
view set to true for the domain, project and role you are working on.
POST: Creates a instance of a given type.
URL pattern
/orchestrator/v2/instancetypes/{name}/instances
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
201 created
Error Response Codes
401 unauthorized

908

IBM Cloud Orchestrator 2.4.0.2: User's Guide

404 not found

500 internal server error
Request
Resource Instance Request
Response
Resource Instance Response
Authorization
Instance provider dependent. Generic Provider: role: admin
GET: Gets an instance of a given type.
URL pattern
/orchestrator/v2/instancetypes/{name}/instances/{id}
Accepts
application/JSON
Content-Type
*/*
Normal Response Codes
401 unauthorized
404 not found
500 internal server error
Response
Resource Instance Response
Authorization
Instance provider dependent. Generic Provider: Access Control Link with
view set to true for the domain, project and role you are working on.
PUT: Updates an instance of a given type.
URL pattern
/orchestrator/v2/instancetypes/{name}/instances/{id}
Accepts
application/JSON
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Request
Resource Instance Request (partial)
Response
Resource Instance Request

Chapter 11. Reference

909

Authorization
Instance provider dependent. Generic Provider: Access Control Link with
modify set to true for given domain, project and role you are working on.
DELETE: Deletes an instance of a given type.
URL pattern: /orchestrator/v2/instancetypes/{name}/instances/{id}
Accepts
*/*
Content-Type
application/JSON
Normal response Codes
204
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Authorization
Instance provider dependent. Generic Provider: Access Control Link with
modify set to true for given domain, project and role of the user.
GET: Lists actions defined on a given instance of a given type.
URL pattern: /orchestrator/v2/instancetypes/{name}/instances/{id}/services
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Authorization
Instance provider dependent. Generic Provider: Access Control Link with
view set to true on the instance and services for given domain, project and
role of the user.
POST: Launch given action on a given instance of a given type.
URL pattern: /orchestrator/v2/instancetypes/{name}/instances/{id}/services/
{serviceid}/launch
Content-Type
application/JSON
Normal Response Codes
202 accepted

910

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Error Response Codes

401 unauthorized
404 not found
500 internal server error
Authorization
Instance provider dependent and ACL with use set to true on the services
for given domain, project and role of the user. Access Control Link with
use set to true on the instance and services for given domain, project and
role of the user.
Resource instance providers:
You can use OpenStack, catalog, and generic providers.
OpenStack providers:
You can use the following OpenStack providers.
Domain provider:
This provider lists OpenStack keystone domains.
Instance Type
domain
Provider Class
com.ibm.orchestrator.core.instance.providers.openstack.OpenstackDomainProvider
Table 117.
Attribute
Name

Type

Description

Displayed in
UI

id

String

Instance ID

displayname

String

Name of the
domain

asc/desc

description

String

Description of
the domain

asc/desc

icon

String

Not used

detailsURL

String

URI to display
details of the
domain

parm

String

JSON result
from
OpenStack

enabled

Boolean

Domain
enablement
status

asc/desc

domain

String

Domain ID

tags

String

Tags to control

Sortable

Filterable

Searchable

asc/desc

Chapter 11. Reference

911

Group provider:
This provider lists OpenStack keystone groups.
Instance Type
group
Provider Class
com.ibm.orchestrator.core.instance.providers.openstack.OpenstackGroupProvider
Table 118.
Attribute
name

Type

Description

Displayed in
UI

id

String

Instance ID

displayname

String

Name of the
group

asc/desc

description

String

Description of
the group

asc/desc

icon

String

Not used

detailsURL

String

URI to display
details of the
group

parm

String

JSON result
from
OpenStack

domain

String

Domain ID

tags

String

Tags to control
action
availability

Sortable

Filterable

Searchable

asc/desc

Heat stack provider:

This provider lists OpenStack Heat stacks.
Instance Type
heat
Provider Class
com.ibm.orchestrator.core.instance.providers.openstack.OpenstackHeatStackProvider
Table 119.
Attribute
name

Type

Description

id

String

Instance ID

displayname

String

Name of the
server

description

String

Description of
the server

icon

String

Not used

detailsURL

String

URI to display
details of the
server

912

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Displayed in
UI

Sortable

Filterable

Searchable

asc/desc
asc/desc

Table 119. (continued)

Attribute
name

Type

Description

Displayed in
UI

Sortable

Filterable

parm

String

JSON result
from
OpenStack

status

String

Server status
in OpenStack

asc/desc

openstackId

String

Server ID in
OpenStack

region

String

OpenStack
Region

updated

String

Time of last
update

created

String

Creation time

tags

String

Tags to control
action
availability

Searchable

asc/desc
asc/desc

Project provider:
This provider lists OpenStack keystone projects.
Instance Type
project
Provider Class
com.ibm.orchestrator.core.instance.providers.openstack.OpenstackProjectProvider
Table 120.
Attribute
Name

Type

Description

Displayed in
UI

id

String

Instance ID

displayname

String

Name of the
project

asc/desc

description

String

Description of
the project

asc/desc

icon

String

Not used

detailsURL

String

URI to display
details of the
project

parm

String

JSON result
from
OpenStack

enabled

Boolean

Project
enablement
status

asc/desc

domain

String

Domain ID

tags

String

Tags to control
action
availability

Sortable

Filterable

Searchable

asc/desc

Chapter 11. Reference

913

User provider:
This provider lists OpenStack keystone users.
Instance Type
user
Provider Class
com.ibm.orchestrator.core.instance.providers.openstack.OpenstackUserProvider
Table 121.
Attribute
Name

Type

Description

id

String

Instance ID

displayname

String

Name of the
user

description

String

Description of
the user

icon

String

Not used

detailsURL

String

URI to display
details of the
user

parm

String

JSON result
from
OpenStack

enabled

Boolean

User
enablement
status

defaultProjectId String

Default project
for this user

email

String

Email address
of this user

domain

String

Domain ID

tags

String

Tags to control
action
availability

Displayed in
UI

Sortable

Filterable

Searchable

asc/desc
y

asc/desc

asc/desc

asc/desc

VM provider:
This provider lists OpenStack Nova virtual servers.
Instance Type
openstackvms
Provider Class
com.ibm.orchestrator.core.instance.providers.openstack.OpenstackVMProvider
Table 122.
Displayed
in UI

Attribute Name

Type

Description

id

String

Instance ID

displayname

String

Name of the server

description

String

Description of the
server

914

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Sortable

Filterable

Searchable

asc/desc
asc/desc

Table 122. (continued)

Displayed
in UI

Sortable

Filterable

Server status in
OpenStack

asc/desc

String

OpenStack Region

updated

String

Time of last update

created

String

Creation time

keyPair

String

SSH key pair

patternInstanceType

String

Instance type of the

pattern instance the
server belongs

patternName

String

Name of the pattern

instance the server
belongs

patternURI

String

URI to display details

of the pattern instance
the server belongs

tags

String

tags to control action

availability

ipAddresses

String

IP Adresses assigned to y
the server

Attribute Name

Type

Description

icon

String

Not used

detailsURL

String

URI to display details

of the server

parm

String

JSON result from

OpenStack

openstackId

String

Server ID in OpenStack

status

String

region

Searchable

asc/desc
asc/desc

asc/desc

asc/desc

Self-Service Catalog providers:

You can use the following Self-Service Catalog providers.
Offering provider:
This provider lists Self-Service Catalog offerings.
Instance Type
offering
Provider Class
com.ibm.orchestrator.core.instance.providers.catalog.CatalogOfferingProvider
Table 123.
Attribute
name

Type

Description

id

String

Instance ID

displayname

String

Name of the
offering

description

String

Description of
the offering

Displayed in
UI

Sortable

Filterable

asc/desc

Searchable

asc/desc

asc/desc

Chapter 11. Reference

915

Table 123. (continued)

Attribute
name

Type

Description

icon

String

Offering icon

detailsURL

String

URI to display
details of the
offering

parm

String

JSON result
from Catalog

type

String

Type of this
service

category

String

Category of
this offering

tags

String

Tags to control
action
availability

Displayed in
UI

Sortable

Filterable

asc/desc

Searchable

asc/desc
y

asc/desc

Action provider:
This provider lists instance actions. Actions are services that can be executed on
one or more selected instances.
Instance Type
Offering
Provider Class
com.ibm.orchestrator.core.instance.providers.catalog.CatalogActionProvider
Table 124.
Attribute
name

Type

Description

id

String

Instance ID

displayname

String

Name of the
action

description

String

Description of
the action

icon

String

Action icon

detailsURL

String

URI to display
details of the
action

parm

String

JSON result
from Catalog

type

String

Type of this
service

category

String

Category of
this offering

instancetype

String

Type of
instance upon
which this
action can be
executed

916

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Displayed in
UI

Sortable

Filterable

asc/desc

asc/desc

asc/desc

asc/desc

asc/desc

asc/desc

asc/desc

Searchable

Table 124. (continued)

Attribute
name

Type

Description

Displayed in
UI

tagsAsString

String

Tags combined y
to a single
string

tags

String

Tags to control
action
availability

Sortable

Filterable

Searchable

Catalog Category provider:

This provider lists Self-Service Catalog categories. Categories may contain one or
more offerings.
Instance Type
category
Provider Class
com.ibm.orchestrator.core.instance.providers.catalog.CatalogCategoryProvider
Table 125.
Attribute
name

Type

Description

id

String

Instance ID

displayname

String

Name of the
category

description

String

Description of
the category

icon

String

Category icon

detailsURL

String

URI to display
details of the
category

parm

String

JSON result
from Catalog

tags

String

Tags to control
action
availability

Displayed in
UI

Sortable

Filterable

Searchable

asc/desc

asc/desc

asc/desc

asc/desc

Generic provider:
This provider lists generic resources. The provider may be registered multiple
times under different instance types.
Instance Type
<not registered by default>
Provider Class
com.ibm.orchestrator.core.instance.providers.generic.GenericProvider
Attribute
name

Type

Description

id

String

Instance ID

Displayed in
UI

Sortable

Filterable

asc/desc

Searchable

Chapter 11. Reference

917

Attribute
name

Type

Description

Displayed in
UI

Sortable

Filterable

Searchable

displayname

String

Name of the
instance

asc/desc

description

String

Description of
the instance

asc/desc

icon

String

Instance icon

asc/desc

detailsURL

String

URI to display
details of the
instance

parm

String

JSON object
used to store
additional
information

tags

String

Tags to control
action
availability

Task engine REST API V2

JSON Formats
Task Response
{
"updated_iso" : "2014-03-31T13:05:14+0200",
"description_message" : "The process is complete.",
"domain" : "Default",
"created" : 1396263830875,
"error" : {
"resourceBundle" : "com.ibm.orchestrator.messages.orchestratormessages",
"message" : null,
"messageKey" : "BPM_PROCESS_COMPLETE",
"args" :
[
"3"
]
},
"user" : "ksadmin",
"parm" : {
.....
},
"created_iso" : "2014-03-31T13:03:50+0200",
"status_localized" : "Completed",
"error_message" : "CTJCO0002I: Business process instance 3 completed successfully.",
"status" : "COMPLETED",
"eventTopic" : "com/ibm/orchestrator/serviceinstance/plan/ibm_bpm_process",
"delayInSeconds" : 30,
"project" : "admin",
"id" : "1003",
"updated" : 1396263914896,
"description" : {
"resourceBundle" : "com.ibm.orchestrator.messages.orchestratormessages",
"message" : null,
"messageKey" : "PROCESS_COMPLETE",
"args" :
[
]
}
}

918

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Task Response
[ Task Response 1,....., Task Response n]
GET: Get all tasks
URL method
/orchestrator/v2/tasks
Accepts
*/*
Content-Type
application/JSON
Normal response Codes
200
Error Response Codes
500 internal server error
Request Parameters
Expand: if set to serviceInstance the information service instance referred
by the attribute serviceInstanceId will get returned in the Task Response
in the parameter serviceInstance.
Response
Tasks Response
Authorization
No authorization needed but the output is restricted to tasks from all users
within the current project. Users with role admin can see all the tasks.
POST: Get all tasks
URL method
/orchestrator/v2/tasks
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
201 created
Error Response Codes
401 unauthorized
500 internal server error
Response
Tasks Response
Authorization
role: admin
GET: Get the task with a given id
URL method
/orchestrator/v2/tasks/{id}
Accepts
*/*
Chapter 11. Reference

919

Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
404 not found
500 internal server error
Response
task Response
Authorization
No authorization needed but output restricted to role
PUT : Get the task with a given id
URL pattern
/orchestrator/v2/tasks/{id}
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
200
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Response
Task Response
Authorization
role: admin or in same project as task
DELETE: Delete the task with a given id
URL pattern
/orchestrator/v2/tasks/{id}
Accepts
*/*
Content-Type
application/JSON
Normal response Codes
204
Error Response Codes
401 unauthorized
404 not found
500 internal server error
Response
Task Response

920

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Authorization
role: admin

Configuration providers REST API

Three REST APIs manage the entities under Administration. A REST API consumer
can manage the entities in two ways.
v Manage the entities directly
To manage the entities using the core REST APIs, you must use the core REST
APIs or OpenStack APIs. If you directly manage entities like domains, users,
groups, projects, quotas, you must call the OpenStack APIs. For categories,
offerings and actions you must call the core REST APIs. In both cases, the
actions will not be run and you must handle all the dependencies.
v Process flows
If you leverage the logic of the BPM processes as described above, then you
need to launch the actions through the core REST API. This REST API is
designed for external usage as it involves the business logic that is
implemented by the provider. For example, if the REST API provider decides
to add an approval process to the Modify Quota action of a project, then the
provider forces the REST API consumer to launch the action in order to get
the approval logic applied.
Managing entities using Core REST APIs:
Before you begin
The mapping in table 1 shows which REST APIs are used to manage the entities.
Table 126.
Entity

REST API

Endpoint

Domain

OpenStack Keystone API

v3/domains

Project

OpenStack Keystone API

v3/projects

User

OpenStack Keystone API

v3/users

Group

OpenStack Keystone API

v3/group

Quota

OpenStack Compute API

v2.0/{tenant_id}/os-quotasets

Category

Core REST API

ochestrator/v2/categories

Offering

Core REST API

ochestrator/v2/offerings

Action

Core REST API

ochestrator/v2/offerings

Managing entities using actions:

Any action as described in the Managing Entities using Core Services REST APIs
documentation can be invoked per API. The action must be launched in the Core
Services REST API. The following procedure is an example of how to launch the
Edit Project action on a project via API.
Procedure
1. Get the project provider and the URL for its instances in the instances attribute
of the response.
HTTP method:
GET
Chapter 11. Reference

921

Example:
https://xvm127.boeblingen.de.ibm.com:8443/orchestrator/v2/instancetypes/
project
{
"href": "https://xvm127.boeblingen.de.ibm.com:8443/
orchestrator/v2/instancetypes/project",
"item": {
"provider": "com.ibm.orchestrator.core.instance
.providers.openstack.OpenstackProjectProvider",
"detailsview": {
"application": "SCOMT",
"humanservice": "Show Project Details"
},
"keyfields": [
{
"instanceattribute": "displayname",
"header": "Name"
},
{
"instanceattribute": "description",
"header": "Description"
},
{
"instanceattribute": "enabled",
"header": "Enabled?"
}
],
"tags": [
"enabled",
"disabled"
],
"icon": "Web Icon:glyphicons_232_cloud",
"type": "admin",
"name": "project",
"description": "Show your OpenStack projects.",
"displayname": "Projects"
},
"instances": {
"href":
"https://xvm127.boeblingen.de.ibm.com:8443/orchestrator
/v2/instancetypes/project/instances"
},
"services": {
"href": "https://xvm127.boeblingen.de.ibm.com:8443/
orchestrator/v2/instancetypes/project/services"
}
}

2. Get the instance you want to manage and find the ID and name. You can also
use the API filter to search the name attribute.
HTTP Method:
GET
Example:
https://xvm127.boeblingen.de.ibm.com:8443/orchestrator/v2/instancetypes/
project/instances
{
"href": "https://xvm127.boeblingen.de.ibm.com:8443
/orchestrator/v2/instancetypes/project/instances",
"start": 0,
"limit": 10,
"total": 4,
"first": {
"href":
"https://xvm127.boeblingen.de.ibm.com:8443/orchestrator

922

IBM Cloud Orchestrator 2.4.0.2: User's Guide

/v2/instancetypes/project/instances?_limit=10&_start=0"
},
"previous": null,
"next": null,
"last": {
"href":
"https://xvm127.boeblingen.de.ibm.com:8443
/orchestrator/v2/instancetypes/project/instances?_limit=10&_start=0"
},
"items": [
{
"href":
"https://xvm127.boeblingen.de.ibm.com:8443/
orchestrator/v2/instancetypes/project/instances/
4ae7ade7e4724c69ab90246ea72965e6",
"item": {
"enabled": true,
"domain": "4ae7ade7e4724c69ab90246ea72965e6",
"tags": [
"enabled"
],
"icon": null,
"id": "4ae7ade7e4724c69ab90246ea72965e6",
"parm": {
"enabled": true,
"domain_id": "default",
"links": {
"self":
"http://192.0.2.35:5000/v3/projects
/4ae7ade7e4724c69ab90246ea72965e6"
},
"id": "4ae7ade7e4724c69ab90246ea72965e6",
"name": "admin",
"description": "admin Tenant"
},
"description": "admin Tenant",
"detailsURL":
"https://xvm127.boeblingen.de.ibm.com:8443/teamworks/
executeServiceByName?processApp=SCOMT&serviceName=
Show+Project+Details&tw.local.projectId=
4ae7ade7e4724c69ab90246ea72965e6&tw.local.domainId=
default&tw.local.authUser=admin&tw.local.authDomain=
Default&tw.local.authProject=admin",
"displayname": "admin"
}
},
...
]
}

3. Get the actions that are applicable to projects. Get the link to in the services
attribute of the response in step 1. Get the services and find the Edit Project
action by name and remember its ID.
HTTP method:
GET
Example:
https://xvm127.boeblingen.de.ibm.com:8443/orchestrator/v2/instancetypes/
project/services
...
{
"href": "https://xvm127.boeblingen.de.ibm.com:8443/
orchestrator/v2/instancetypes/project/services/69",
"item": {
"human_service": "Edit Project Action",
"priority": 0,
"human_service_app_name": "SCOrchestrator Multi-Tenancy Toolkit",
Chapter 11. Reference

923

"implementation_type": null,
"created": 1401827772,
"human_service_app_short_name": "SCOMT",
"process_app_id": "2066.227c57b3-a5e5-4e5b-a283-c920cf9bed50",
"acl": [
...
],
"name": "Edit Project",
"ownerid": 0,
"instancetype": "project",
"process": "Edit Project Action",
"operation_type": "singleInstanceAction",
"human_service_app_id": "2066.227c57b3-a5e5-4e5b-a283-c920cf9bed50",
"tags": [
"enabled"
],
"process_app_name": "SCOrchestrator Multi-Tenancy Toolkit",
"icon": "act16_return",
"updated": 1401827772,
"id": 69,
"process_app_short_name": "SCOMT",
"description": "Edit the project details",
"category": 31
}
},
...

4. Launch the action with the ID from step 3, passing the ID of the selected
instance (project) from step 2 in the request body. The call returns a task which
is in the state NEW and a new ID.
Note: For all actions of type "createInstance", the ID of the domain must be
passed in the "instances" array of the PUT request.
HTTP method:
POST
Body:
{
"instances": ["default"]
}

Example:
https://xvm127.boeblingen.de.ibm.com:8443/orchestrator/v2/instancetypes/
project/services/69/launch
{
"updated_iso": "1970-01-01T01:00:00+0100",
"description_message": "HS_OFFERING_INVOCATION",
"domain": "Default",
"message": "Launched",
"created": 1402569924045,
"error": null,
"user": "admin",
"parm": {
"plan": {
"human_service": "Edit Project Action",
"priority": 0,
"human_service_app_name": "SCOrchestrator Multi-Tenancy
Toolkit",
"implementation_type": null,
"created": 1401827772,
"human_service_app_short_name": "SCOMT",
"process_app_id": "2066.227c57b3-a5e5-4e5b-a283-c920cf9bed50",
"acl": [
...
],

924

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"name": "Edit Project",

"ownerid": 0,
"instancetype": "project",
"process": "Edit Project Action",
"operation_type": "singleInstanceAction",
"human_service_app_id": "2066.227c57b3-a5e5-4e5b-a283c920cf9bed50",
"tags": [
"enabled"
],
"process_app_name": "SCOrchestrator Multi-Tenancy Toolkit",
"icon": "act16_return",
"updated": 1401827772,
"id": 69,
"process_app_short_name": "SCOMT",
"description": "Edit the project details",
"category": 31
},
"instances": [
"default"
]
},
"created_iso": "2014-06-12T12:45:24+0200",
"status_localized": "New",
"error_message": null,
"status": "NEW",
"eventTopic": "com/ibm/orchestrator/serviceinstance/plan
/ibm_bpm_process",
"delayInSeconds": 0,
"project": "admin",
"id": "1521",
"updated": 0,
"redirect": "/teamworks/executeServiceByName?
processApp=SCOMT&serviceName=Edit+Project+Action&tw.
local.operationContextId=1521",
"description": {
"resourceBundle": "com.ibm.orchestrator.messages.
orchestratormessages",
"message": "HS_OFFERING_INVOCATION",
"messageKey": "HS_OFFERING_INVOCATION",
"args": [
"Edit Project"
]
}
}

5. Set the parameters of the task which are the input for the action. Then set the
status of the task to QUEUED to queue the task for execution. In the body the
description is set to test and the other attributes remain the same.
HTTP method:
PUT
Body:
{
"status":"QUEUED",
"parm":{"OperationParameter":"<variable type=\"Project\">\n
<name type=\"String\"><![CDATA[admin]]><\/name>\n
<description type=\"String\"><![CDATA[test]]>
<\/description>\n
<enabled type=\"Boolean\"><![CDATA[true]]><\/enabled>\n
<id type=\"String\"><![CDATA[
4ae7ade7e4724c69ab90246ea72965e6]]><\/id>\n
<domainId type=\"String\"><![CDATA[default]]>
<\/domainId>\n<\/variable>"}
}

Example:
Chapter 11. Reference

925

https://xvm127.boeblingen.de.ibm.com:8443/kernel/tasks/1521
6. Check if the task succeeded or failed. The status will switch to RUNNING. If
the task succeeds the status says COMPLETED. If the task fails the status says
FAILED and an error_message is shown. In the example, the process
completed.
HTTP method:
GET
Example:
https://xvm127.boeblingen.de.ibm.com:8443/kernel/tasks/1521
{
"error_message": "CTJCO0002I: Business process instance 79
completed successfully.",
"status": "COMPLETED",
}

7. Verify if the action applied the changes on the entity. Finally, it is possible to
ensure if the change happened on the instance.
HTTP method:
GET
Example:
https://xvm127.boeblingen.de.ibm.com:8443/orchestrator/v2/instancetypes/
project/instances/4ae7ade7e4724c69ab90246ea72965e6
{
"href": "https://xvm127.boeblingen.de.ibm.com:8443/orchestrator/v2
/instancetypes/project
/instances/4ae7ade7e4724c69ab90246ea72965e6",
"item": {
"enabled": true,
"domain": "4ae7ade7e4724c69ab90246ea72965e6",
"tags": [
"enabled"
],
"icon": null,
"id": "4ae7ade7e4724c69ab90246ea72965e6",
"parm": {
"enabled": true,
"domain_id": "default",
"links": {
"self": "http://192.0.2.35:5000/v3/projects
/4ae7ade7e4724c69ab90246ea72965e6"
},
"id": "4ae7ade7e4724c69ab90246ea72965e6",
"name": "admin",
"description": "test"
},
"description": "test",
"detailsURL":
"https://xvm127.boeblingen.de.ibm.com:8443
/teamworks/executeServiceByName?processApp=SCOMT&serviceName
=Show+Project+Details&tw.local.
projectId=4ae7ade7e4724c69ab90246ea72965e6&tw.local.
domainId=default&tw.local.authUser=admin&tw.local
.authDomain=Default&tw.local.authProject=admin",
"displayname": "admin"
}
}

926

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Core REST API for compatibility with earlier versions

The REST APIs described in the following sections were replaced in IBM Cloud
Orchestrator but they are still valid for compatibility with SmartCloud Orchestrator
2.3.
Self-service offering REST API:
You can use this set of REST API calls to interact with the self-service offerings in
IBM Cloud Orchestrator.
Create a self-service offering:
Use this REST call to create a self-service offering.
Available HTTP method
Table 127. Create a self-service offering REST API call
HTTP method

POST

URL pattern

https://hostname/resources/services

Response

The response of the server contains the specified offering. It has the
following set of attributes:
{
category:
created:
description:
human_service:
human_service_app_id:
human_service_app_name:
human_service_app_short_name:
icon:
id:
implementation_type:
name:
operation_type:
ownerid:
process:
process_app_id:
process_app_name:
process_app_short_name:
updated:
}

Return values

v 201 Returns the created service or offering

v 500 Internal service error

An entry has the following attributes:

v category - optional, the category to which the offering belongs.
v created - the creation time of the self-service offering, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and
is automatically generated by the product.
v description - optional, a short description of the offer ing.
v human_service - optional, the URL of an IBM Business Process Manager human
service (coach), a user interface to provide user input.
v human_service_app_id - optional, depending on the human_service attribute, the
ID of the IBM Business Process Manager application to which the human service
belongs.
Chapter 11. Reference

927

v human_service_app_name - optional, depends on if the human_service attribute is

set, the name of the IBM Business Process Manager application to which the
human service belongs.
v human_service_app_short_name - the short name of the IBM Business Process
Manager human service application.
v icon - optional, an offering can have an icon assigned that is displayed inside
the Self-Service Catalog.
v id - the ID of the offering.
v implementation_type - the two possible values are 'ibm_bpm_process and
script.
v name - the name of the offering.
v operation_type - the only possible value is "service".
v ownerid - the owner of the user who triggered the offering.
v process - the name of the IBM Business Process Manager process bound to the
offering.
v process_app_id - the ID of the IBM Business Process Manager application in
which the process is defined.
v process_app_name - the name of the IBM Business Process Manager application
in which the process is defined.
v process_app_short_name - the short name of the IBM Business Process Manager
process application.
v updated - the time when the self-service offering was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This value
is numeric and is automatically generated by the product.
The following listing shows an example response that can be retrieved by way of
the request:
{
"human_service": "Sample_ReportProblem",
"human_service_app_name": "SCOrchestrator_Toolkit",
"implementation_type": "ibm_bpm_process",
"human_service_app_short_name": "SCOTLKT",
"process_app_id": "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"name": "Problem report",
"created": 1242965374865,
"updated": 1242965392870,
"ownerid": 2,
"process": "Sample_Report",
"operation_type": "service",
"human_service_app_id": "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"process_app_name": "SCOrchestrator_Toolkit",
"icon": "Configuration Icon:ge100_config_24",
"id": 5,
"process_app_short_name": "SCOTLKT",
"description": "Report a problem",
"category": ""
}

928

IBM Cloud Orchestrator 2.4.0.2: User's Guide

List all self-service offerings:

Use this REST API method to list all self-service offerings.
Available HTTP method
Table 128. Get list of all self-service offerings
HTTP method

GET

URL pattern

https://hostname/resources/services

Response

The response of the server contains a list of available self-service

offerings. Each offering has the following set of attributes:
{
category:
created:
description:
human_service:
human_service_app_id:
icon:
id:
implementation_type:
name:
operation_type:
ownerid:
process:
process_app_id:
updated:
}

Return values

v 200 Returns the list of offerings

v 500 Internal server error

An entry has the following attributes:

v category - optional, a category to which the offering belongs.
v created - the creation time of the self-service offering, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and
is automatically generated by the product.
v description - optional, a short description for the offering.
v human_service - optional, the URL of an IBM Business Process Manager human
service (coach), a user interface to provide user input.
v human_service_app_id - optional, depending on the human_service attribute. The
ID of the IBM Business Process Manager application to which the human_service
belongs.
v icon - optional, an offering can have an icon assigned that will be displayed
inside the Self-Service Catalog.
v id - ID of the offering.
v implementation_type - possible values are ibm_bpm_process or script.
v name - the name of the offering.
v operation_type - the only possible value is 'service'.
v ownerid - the owner of the user who triggered the offering.
v process - the name of the IBM Business Process Manager process bound to the
offering.
v process_app_id - the ID of the IBM Business Process Manager application in
which a process is defined.

Chapter 11. Reference

929

v updated - the time when the self-service offering was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This value
is numeric and is automatically generated by the product.
The following listing shows an example response that can be retrieved by way of
the request:
[
{
"human_service": "Sample_ReportProblem",
"implementation_type": "ibm_bpm_process",
"process_app_id": "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"name": "Problem report",
"created": 1242965374865,
"updated": 1242965392870,
"ownerid": 2,
"process": "Sample_Report",
"operation_type": "service",
"human_service_app_id": "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"icon": "Job Icon:ge100_job_24",
"id": 5,
"description": "Report a problem",
"category": 5
}
]

Get entries for a specific self-service offering:

Use this REST call to retrieve information about a self-service offering with a
specified ID.
Available HTTP method
Table 129. Get entries for a specific self-service offering REST API call
HTTP method

GET

URL pattern

https://hostname/resources/services/{id}[?acl=true]

Response

The response of the server contains the specified offering. It has the
following set of attributes:
{
acl:
category:
created:
description:
human_service:
human_service_app_id:
human_service_app_name:
human_service_app_short_name:
icon:
id:
implementation_type:
name:
operation_type:
ownerid:
process:
process_app_id:
process_app_name:
process_app_short_name:
updated:
}
Note: The acl attribute is only returned when the optional query
parameter acl is passed with the value true.

930

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 129. Get entries for a specific self-service offering REST API call (continued)
Return values

v 200 Returns the service or offering associated with the given ID

v 403 If the client is not on the offering's ACL, they are not
authorized to perform this action.
v

404 No offering exists with the given ID

v 500 Internal server error

An entry has the following attributes:

v category - optional, the category to which the offering belongs.
v created - the creation time of the self-service offering, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and
is automatically generated by the product.
v description - optional, a short description of the offering.
v human_service - optional, the URL of an IBM Business Process Manager human
service (coach), a user interface to provide user input.
v human_service_app_id - optional, depending on the human_service attribute, the
ID of the IBM Business Process Manager application to which the human service
belongs.
v human_service_app_name - optional, depends on if the human_service attribute is
set, the name of the IBM Business Process Manager application to which the
human service belongs.
v human_service_app_short_name - the short name of the IBM Business Process
Manager human service application.
v icon - optional, an offering can have an icon assigned that is displayed inside
the Self-Service Catalog.
v id - the ID of the offering.
v implementation_type - the two possible values are 'ibm_bpm_process and
script.
v name - the name of the offering.
v operation_type - the only possible value is "service".
v ownerid - the owner of the user who triggered the offering.
v process - the name of the IBM Business Process Manager process bound to the
offering.
v process_app_id - the ID of the IBM Business Process Manager application in
which the process is defined.
v process_app_name - the name of the IBM Business Process Manager application
in which the process is defined.
v process_app_short_name - the short name of the IBM Business Process Manager
process application.
v updated - the time when the self-service offering was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This value
is numeric and is automatically generated by the product.
The following listing shows an example response that can be retrieved by way of
the request:
{
"human_service": "Sample_ReportProblem",
"human_service_app_name": "SCOrchestrator_Toolkit",
"implementation_type": "ibm_bpm_process",
"human_service_app_short_name": "SCOTLKT",
Chapter 11. Reference

931

"process_app_id": "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"name": "Problem report",
"created": 1242965374865,
"updated": 1242965392870,
"ownerid": 2,
"process": "Sample_Report",
"operation_type": "service",
"human_service_app_id": "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"process_app_name": "SCOrchestrator_Toolkit",
"icon": "Configuration Icon:ge100_config_24",
"id": 5,
"process_app_short_name": "SCOTLKT",
"description": "Report a problem",
"category": 5
}
"acl":
[
{
"domain": "default",
"view": true,
"role": "default",
"use": false,
"resourceType": "SCOService",
"project": "default",
"resourceId": 101,
"modify": true,
"id": 151
}
]

Delete a specific self-service offering:

Use this REST API call to delete a specific self-service offering.
Available HTTP method
Table 130. Delete a self-service offering REST API call
HTTP method

DELETE

URL pattern

https://hostname/resources/services/{id}

Response

The self-service offering is deleted.

Return values

v 204 Deletes an offering and its ACL

v 401 The client is not authorized to perform this action as they
are not on the offering's ACL
v 404 No offering has the given ID.
v 500 Internal server error

Update a specific self-service offering:

Use this REST API call to update a specific self-service offering
Available HTTP method
Table 131. Update a self-service offering REST API call

932

HTTP method

PUT

URL pattern

https://hostname/resources/services/{id}

Response

The self-service offering is updated.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 131. Update a self-service offering REST API call (continued)

Return values

v 201 - Updates an existing offering

v 400 - Decode failure. Request body does not contain valid JSON
v 401 - Authorization failure
v 404 - Update failure
v 500 - Internal server error

Structure of request body:

{

"<attribute>": "<attribute_value>" }

The following listing shows sample content of request body to update the
description of a self-service offering:
{

"description": "Changed description" }

Executing a self-service offering:

Three different scenarios are supported.
Executing a self-service offering which does not have any parameters
In this scenario only one REST-call is required:
REST POST /resources/automation/<offering-id>

(IDs for the offerings can be retrieved with REST GET /resources/services).
Executing self-service offering without human service providing all
parameters
1. Run REST POST /resources/automation/<offering-id>
2. Retrieve the <request-id> from the response.
3. Run REST PUT /kernel/tasks/<request-id> with required parameters as
payload.
Executing self-service offering with human service to collect all the required
parameters through the UI
1. Run REST POST /resources/automation/<offering-id>
2. Get <human-service-url> from the response.
3. Use the URL in an iframe, for example, to display the user interface and collect
parameters (when you click Submit, the business process is kicked off).
Step 1 - Start the request by creating the operation context
Use the IBM Cloud Orchestrator interface to create the operationContext by
posting to the offering API. Note the mandatory API version and content-type
headers, and the empty json object {} we send over, an offering with ID equal to 31
is used in this example:
curl -ku admin:passw0rd -H "X-IBM-Workload-Deployer-API-Version: 3.1"
-H "Content-Type: application/json"
--data-binary {} https://10.102.98.11/resources/automation/31

This is all that needs to be done for scenario A. For scenario B, search for the
request ID in the response of the call:
{..."id": "1004", ...}
Chapter 11. Reference

933

or in case of scenario C (delegated UI), search for the human service URL:
{.... "redirect": "/teamworks/executeServiceByName?
processApp=SCOTLKT&serviceName=Sample_UserInterface&tw.local.operationContextId=1004",...}

For scenario C, use the URL in an iframe, for example, to display the user interface
and collect parameters (when you click Submit, the business process is kicked off).
Step 2 - Trigger the execution of the offering workflow (Business Process
Manager process)
Step 2 is only required for scenario B. This step passes the parameters to Business
Process Manager process and starts the process, use the request ID from the
previous step.
Sample call: this call passes the values Hello and Phone for a
Sample_BusinessObject consisting of two string attributes (field1 and field2):
curl -ku admin:passw0rd -X PUT -d {"status":"QUEUED", "parm":{"OperationParameter":
"<variable type=\"Sample_BusinessObject\">
<field1 type=\"String\"><![CDATA[Hello]]><\/field1>
<field2 type=\"String\"><![CDATA[Phone]]><\/field2> <\/variable>"}}
-H "Content-Type: application/json" https://10.102.98.11/kernel/tasks/1004

where status must be set to QUEUED so that the process is started, and parm must
contain the input values for the process the values must be passed in the
serialized form of the related Business Process Manager business object as returned
by the Business Process Manager
tw.system.serializer.toXML(tw.local.inputParameterObject)

How to get details about the input parameter datatype

In case you need to programmatically introspect input parameters of the offering
workflow the following things can be performed:
v Use REST interface of IBM Cloud Orchestrator to retrieve details about a
registered offering:
GET .../resources/services/{id}

Among the data there are:

process
The name of the IBM Business Process Manager process bound to the
offering.
process_app_id
The ID of the IBM Business Process Manager application in which the
process is defined.
For details, refer to Get entries for a specific self-service offering on page 930.
v Use REST Interface for BPD-related resources to get details about exposed items:
GET .../rest/bpm/wle/v1/exposed

Find the process with display=process and processAppID=process_app_id.

{"status":"200", "data":{ "exposedItemsList":[ { "type":"process",
"itemID":"25.8403dd37-e049-46f5-8952-b7a46f0d198f",
"processAppID":"2066.931b0053-02bd-4f47-ac72-4eb527457383",
"snapshotID":"2064.73dd1d1a-b533-46ef-ba79-c94cb3b0de87", "snapshotName":"version 2.8.1",
"display":"HR Open New Position", "ID":"2015.204" }

934

IBM Cloud Orchestrator 2.4.0.2: User's Guide

For details, refer to http://www.ibm.com/support/knowledgecenter/

SSFTDH_8.5.0/com.ibm.wbpm.ref.doc/rest/bpmrest/
rest_bpm_wle_v1_exposed.htm.
v Use REST Interface for BPD-related resources to get details about the process
model:
GET .../rest/bpm/wle/v1/processModel/{bpdId}?processAppId={string}&parts=dataModel

You may want to use "parts=all" which will then return more information
about the process such as detailed descriptions. For the bpdId use itemID from
above, for processAppId use the one above:
{ "status":"200", "data":{ ..., "DataModel":{ ...} } }

For details, refer to http://www.ibm.com/support/knowledgecenter/

SSFTDH_8.5.0/com.ibm.wbpm.ref.doc/rest/bpmrest/
rest_bpm_wle_v1_processmodel_bpdid_get.htm
Sample Output:
Note that only the bold sections in the following output excerpt are of interest:
v Getting the type of the inputParameterObject
v Getting the type detailed information, here the parameters to that service are
two string parameters named filed1 and field2
{
"status" : "200",
"data" : {
"DataModel" : {
"properties" : {
"message" : { "type" : "String", "isList" : false },
"returnFromRest" : { "type" : "String", "isList" : false }
},
"inputs" : {
"operationContext" : { "type" : "OperationContext", "isList" : false },
"inputParameterObject" : { "type" : "Sample_BusinessObject", "isList" : false }
},
...
"Sample_BusinessObject" : {
"properties" : { "field1" : { "isList" : false, "type" : "String },
"field2" : { "isList" : false, "type" : "String }
},
type" : "object",
"ID" : "12.2c079fa7-89a0-426c-a3c1-079be08930ac",
"isShared" : false
},
...

How to get an example for the input parameter payload

In case you need to get an example of the input parameter payload, you can
trigger a request through the IBM Cloud Orchestrator and query the input
parameters of the request (it could be still running or even finished already).
Therefore you must:
1. Retrieve the request ID.
2. Retrieve the input parameters for that request.
To get the request ID, select the triggered request in the REQUEST HISTORY
view and note the request ID as listed in the address bar and as part of the request
details on the right portion of the panel.
Chapter 11. Reference

935

Now using the REST call to retrieve details about the request use:
GET .../kernel/tasks/{request-id}

for example:
curl -ku admin:passw0rd -H "X-IBM-Workload-Deployer-API-Version: 3.1"
-H "Content-Type: application/json" https://192.0.2.114/kernel/tasks/2472"

Within the response, search for Operation Parameter. Sample excerpt:

"OperationParameter" : "<variable type=\"MyRequest\"
<vpmoNumber type=\"Integer\"><![CDATA[116560]]><\/vpmoNumber>
<appId type=\"Integer\"><![CDATA[19073]]><\/appId>
<attuidNo type=\"String\"><![CDATA[dw945f]]><\/attuidNo>
<serverType type=\"NameValuePair\">
<name type=\"String\"><![CDATA[Test]]<\/name>
<value type=\"String\"><![CDATA[T]]><\/value>
<\/serverType>
...

How to get information about a request

Once a request is started the IBM Cloud Orchestrator system can be queried for
the actual status of that request. This is done using the REST call:
GET /kernel/tasks/{id}

For example:
curl -ku admin:passw0rd -H "X-IBM-Workload-Deployer-API-Version: 3.1"
-H "Content-Type:application/json" https://192.0.2.114/kernel/tasks/2472 -X GET

Among other information, the response contains information about the STATUS of
the request. For details on possible values, refer to Get entries for a specific task
on page 948Sample response (excerpt) from REST GET /kernel/tasks/{id}:
{
"updated_iso" : "2014-02-19T17:54:15+0100",
"description_message" : "PROCESS_COMPLETE",
"domain" : "Default",
"created" : 1392828461580,
"error" : { ... },
"serviceInstance" : {
"virtualMachines" : [{
"memory" : 4096,
"hypervisorid" : "\/resources\/hypervisors\/PM-1",
"hostname" : "SC-192-168-0-103.RegionOne.example.com",
....
}
],
....
},
"user" : "admin",
"parm" : {
"startPlanByPlugpointEventHandler" : "done",
"CUSTOM_PARM1": "abc",
"CUSTOM_PARM2": "xyz",
"OperationParameter" : "<variable ...<\/variable>",
"serviceInstanceId" : "282",
"plan" : { ... },
"processId" : "1356"
},
"created_iso" : "2014-02-19T17:47:41+0100",
"status_localized" : "TASKSTATUS_COMPLETED",

936

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"error_message" : "BPM_PROCESS_COMPLETE",
"status" : "COMPLETED",
"eventTopic" :
"com\/ibm\/orchestrator\/serviceinstance\/plan\/ibm_bpm_process",
"delayInSeconds" : 30,
"project" : "admin",
...
}
}

Once the request has finished, there may be the need to retrieve further
information about what has been done by this request. If this is needed, the
Business Process Manager process can use certain building blocks (Integration
Services) to store process specific information in the request (actually in the
operation context).
For details, see Integration services.
The two integration services of interest here are SetOperationContextParameters
and SetServiceInstanceId.
SetOperationContextParameters enables the Process Designer to easily store any
custom specific set of key/value pairs in the operation context object. These
parameters are then part of the response of the GET /kernel/tasks/{id} REST call.
The key/value pairs will be added to the parm section in the response. This
capability can be used to either transfer data from human service to execution
process, or to store information in the operation context which is useful to be
retrieved programmatically once the request has finished.
SetServiceInstanceId enables the Process Designer to store the ID of the service
instance in the operation context. This is useful if the process is about creating a
virtual service instance, and therefore as a result of this process, a reference to the
newly provisioned virtual system instance should be stored. The virtual system
instance ID as provided by the deploy pattern building block can be used to store
as the service instance ID in the operation context. If the operation context contains
a valid service instance ID, the REST call GET /kernel/tasks/{id} can be used to
get all information of the virtual service instance in the response. Therefore use GET
/kernel/tasks/{id}?expand=serviceInstance.
In the sample response above the following lines are of interest:
v If SetServiceInstanceId is used, the following property will be in the response
in the parm section:
"serviceInstanceId" : "282"

v If ?expand=serviceInstance is used for the REST call, the following section will
be part of the response:
"serviceInstance" : {
"virtualMachines" : [{
"memory" : 4096,
"hypervisorid" : "\/resources\/hypervisors\/PM-1",
"hostname" : "SC-192-168-0-103.RegionOne.example.com",

v If SetOperationContextParameters is used the following two custom properties

will show up in the response in the parm section:
"CUSTOM_PARM1": "abc",
"CUSTOM_PARM2": "xyz",

These two custom parameters have been added to the key/value map in the
business process by using the following Java script code, for example:
Chapter 11. Reference

937

tw.local.parMap = new tw.object.Map();

tw.local.parMap.put(CUSTOM_PARM1, abc);
tw.local.parMap.put(CUSTOM_PARM2, xyz);

and mapping the local variable parMap as input for

SetOperationContextParameters.
Note: You only need to set the operation context ID and the parameters; all other
input can be left off, the defaults are fine here.
End-To-End example
To execute the Stop Virtual System Instance Self-Service offering:
1. Get the ID value of the Virtual System to stop:
curl -v -ku admin:passw0rd -H "X-IBM-Workload-Deployer-API-Version: 3.1"
https://192.0.2.98/resources/virtualSystems -X GET
...
{
"desiredstatus_text": null,
"currentstatus_text": "Started",
"name": "GP_wmbhve",
"desiredstatus": null,
"pattern": "/resources/patterns/22",
"id": 3,
"currentmessage_text": "Virtual system is ready",
"created": 1391537634322,
"currentstatus": "RM01006",
"creator": "admin",
"currentmessage": "RM07009",
"owner": "/resources/users/40",
"updated": 1391723628540
}
...

2. Get the ID, the process_app_id, and the process value of the offering to
execute:
curl -ku admin:passw0rd -H "X-IBM-Workload-Deployer-API-Version: 3.1"
-H "Content-Type:application/json" https://192.0.2.98/resources/services -X GET
...
{
"human_service": "Stop Single vSys Instance",
"implementation_type": "ibm_bpm_process",
"created": 1390828290449,
"process_app_id": "2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"name": "Stop Virtual System Instance",
"ownerid": 40,
"process": "Stop Single vSys Pattern Instance",
"operation_type": "service",
"human_service_app_id": "2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"icon": "Cloud Icon:ge100_virtualfabric_24",
"updated": 1390828290449,
"id": 3,
"description": "",
"category": "2"
}
...

3. Create the operation context by passing the ID that you got in Step 2 and
getting the ID value from the response:
curl -ku admin:passw0rd -H "X-IBM-Workload-Deployer-API-Version: 3.1"
-H "Content-Type:application/json" -d {} https://192.0.2.98/resources/automation/3
-X POST

938

IBM Cloud Orchestrator 2.4.0.2: User's Guide

(example):
{
"updated_iso": "2014-02-06T16:15:34-0500",
"description_message": "Starting offering Stop Virtual System Instance. ",
"domain": "Default",
"message": "The action was submitted successfully. See the History section of this
instance to track the action progress.",
"created": 1391721334473,
"error": null,
"user": "admin",
"parm": {
"plan": {
"human_service": "Stop Single vSys Instance",
"priority": 5,
"human_service_app_name": "SCOrchestrator_Support_vSys_Toolkit",
"implementation_type": "ibm_bpm_process",
"human_service_app_short_name": "SCOVSYS",
"created": 1390828290449,
"process_app_id": "2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"name": "Stop Virtual System Instance",
"ownerid": 40,
"process": "Stop Single vSys Pattern Instance",
"operation_type": "service",
"human_service_app_id": "2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"process_app_name": "SCOrchestrator_Support_vSys_Toolkit",
"icon": "CTJCO1138Ige100_virtualfabric_24",
"event": null,
"updated": 1390828290449,
"id": 3,
"process_app_short_name": "SCOVSYS",
"description": "",
"category": "2",
"apply_to_all_pattern": 0
}
},
"created_iso": "2014-02-06T16:15:34-0500",
"status_localized": "New",
"error_message": null,
"status": "NEW",
"eventTopic": "com/ibm/orchestrator/serviceinstance/plan/ibm_bpm_process",
"delayInSeconds": 0,
"project": "admin",
"updated": 1391721334479,
"id": "1025",
"redirect": "/teamworks/executeServiceByName?processApp=SCOVSYS&serviceName=
Stop+Single+vSys+Instance&tw.local.operationContextId=1025",
"description": {
"resourceBundle": "com.ibm.orchestrator.messages.orchestratormessages",
"message": "OFFERING_INVOCATION",
"messageKey": "OFFERING_INVOCATION",
"args": [
"Stop Virtual System Instance"
]
}
}

4. Get details about the input parameters:

a. Get the itemId value from the response, searching for the process and the
process_app_id values got in Step 2:
curl -v -ku admin:passw0rd https://192.0.2.99:9443/rest/bpm/wle/v1/exposed -X GET
...
{"type":"process","itemID":"25.f2899c1e-2884-4009-96d6-581f4bcef980",
"itemReference":"/25.f2899c1e-2884-4009-96d6-581f4bcef980",
"processAppID":"2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"snapshotID":"2064.f3012098-d3f0-4609-8aff-acf0038c9f78",
"snapshotName":"2300_20131029",
Chapter 11. Reference

939

"snapshotCreatedOn":"2013-10-29T14:55:24Z",
"display":"Stop Single vSys Pattern Instance",
"tip":true,
"branchID":"2063.44ef08ae-2760-4d2b-ab11-7de7b3475617",
"branchName":"Main",
"startURL":"/rest/bpm/wle/v1/process?action=start
&bpdId=25.f2899c1e-2884-4009-96d6-581f4bcef980
&processAppId=2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"topLevelToolkitAcronym":"SCOVSYS",
"topLevelToolkitName":"SCOrchestrator_Support_vSys_Toolkit",
"isDe fault":false,"ID":"2015.363"}

b. Get details about the process model, passing the idemId that you got in step
a and the process_app_id that you got in Step 2:
curl -v -ku admin:passw0rd
https://192.0.2.99:9443/rest/bpm/wle/v1/processModel/25.f2899c1e-2884-4009-96d6-581f4bcef980
?processAppId=2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e&parts=dataModel -X GET

(example):
{"status":"200",
...
"inputs":{"operationContext":{"type":"OperationContext","isList":false},
"inputParameterObject":{"type":"VirtualSystem","isList":false}},
...
"VirtualSystem":{
...
"properties":{"currentstatus_text":{"isList":false,"type":"String"},
"envProfileId":{"isList":false,"type":"String"},
"currentstatus":{"isList":false,"type":"String"},
"name":{"isList":false,"type":"String"},
"id":{"isList":false,"type":"String"},
"currentmessage":{"isList":false,"type":"String"}}
...
}

5. Start the execution of the offering, passing in the ID of the Virtual System to
stop that you got from Step 1, and the task ID value that you got from Step 3:
curl -ku admin:passw0rd -X PUT -d {"status":"QUEUED",
"parm":{"OperationParameter":"<variable type=\"VirtualSystem\">
<id type=\"String\"><![CDATA[3]]><\/id;<\/variable>"}}
-H "Content-Type: application/json" https://192.0.2.98/kernel/tasks/1025
{"updated_iso":"2014-02-06T17:34:35-0500",
"description_message":"Starting offering Stop Virtual System Instance. ",
"domain":"Default","created":1391726039661,"error":null,"user":"admin","parm":
{"OperationParameter":"<variable type=\"VirtualSystem\"><id type=\"String\"><![CDATA[3]]>
<\/id><\/variable>","plan":{"human_service":"Stop Single vSys Instance","priority":5,
"human_service_app_name":"SCOrchestrator_Support_vSys_Toolkit",
"implementation_type":"ibm_bpm_process","human_service_app_short_name":"SCOVSYS",
"created":1390828290449,"process_app_id":"2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"name":"Stop Virtual System Instance","ownerid":40,
"process":"Stop Single vSys Pattern Instance","operation_type":"service",
"human_service_app_id":"2066.6ecd41b3-6c42-47e4-a69e-117d77f4104e",
"icon":"CTJCO1138Ige100_virtualfabric_24",
"process_app_name":"SCOrchestrator_Support_vSys_Toolkit","event":null,"id":3,
"updated":1390828290449,"description":"","process_app_short_name":"SCOVSYS",
"category":"2","apply_to_all_pattern":0}}

940

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Self-service catalog REST API:

You can use this set of REST API calls to interact with the Self-Service Catalog in
IBM Cloud Orchestrator.
Table 132. Categories
ID

The unique identifier of the category

Name

The name of the category, that is, the name that appears in the
service catalog

Description

The description of the category

Icon

The name of the icon that is used to represent the category

Isbuiltin

"1 or 0" for "true or false" whether the category is provided by the
product

Create category:
Use this REST call to create a category.
Available HTTP method
Table 133. Create a category REST API call
HTTP method

POST

URL pattern

/resources/automationcategories

Response

The response of the server contains the specified offering. It has the
following set of attributes:
{
category:
created:
description:
human_service:
human_service_app_id:
human_service_app_name:
human_service_app_short_name:
icon:
id:
implementation_type:
name:
operation_type:
ownerid:
process:
process_app_id:
process_app_name:
process_app_short_name:
updated:
}

An entry has the following attributes:

v category - optional, the category to which the offering belongs.
v created - the creation time of the self-service offering, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and
is automatically generated by the product.
v description - optional, a short description of the offering.
v human_service - optional, the URL of an IBM Business Process Manager human
service (coach), a user interface to provide user input.
Chapter 11. Reference

941

v human_service_app_id - optional, depending on the human_service attribute, the

ID of the IBM Business Process Manager application to which the human service
belongs.
v human_service_app_name - optional, depends on if the human_service attribute is
set, the name of the IBM Business Process Manager application to which the
human service belongs.
v human_service_app_short_name - the short name of the IBM Business Process
Manager human service application.
v icon - optional, an offering can have an icon assigned that is displayed inside
the Self-Service Catalog.
v id - the ID of the offering.
v implementation_type - the two possible values are 'ibm_bpm_process and
script.
v name - the name of the offering.
v operation_type - the only possible value is "service".
v ownerid - the owner of the user who triggered the offering.
v process - the name of the IBM Business Process Manager process bound to the
offering.
v process_app_id - the ID of the IBM Business Process Manager application in
which the process is defined.
v process_app_name - the name of the IBM Business Process Manager application
in which the process is defined.
v process_app_short_name - the short name of the IBM Business Process Manager
process application.
v updated - the time when the self-service offering was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This value
is numeric and is automatically generated by the product.
{
"isbuiltin": 0,
"icon": "Web Category Icon:ge100_webcatalog_24",
"name": "Bucket",
"description": ""
}

Get the list of categories:

Use this REST call to get a list of categories.
Available HTTP method
Table 134. Get the list of categories REST API call

942

HTTP method

GET

URL pattern

/resources/automationcategories

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 134. Get the list of categories REST API call (continued)
Response

The response of the server contains the specified offering. It has the
following set of attributes:
{
category:
created:
description:
human_service:
human_service_app_id:
human_service_app_name:
human_service_app_short_name:
icon:
id:
implementation_type:
name:
operation_type:
ownerid:
process:
process_app_id:
process_app_name:
process_app_short_name:
updated:
}

An entry has the following attributes:

v category - optional, the category to which the offering belongs.
v created - the creation time of the self-service offering, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and
is automatically generated by the product.
v description - optional, a short description of the offering.
v human_service - optional, the URL of an IBM Business Process Manager human
service (coach), a user interface to provide user input.
v human_service_app_id - optional, depending on the human_service attribute, the
ID of the IBM Business Process Manager application to which the human service
belongs.
v human_service_app_name - optional, depends on if the human_service attribute is
set, the name of the IBM Business Process Manager application to which the
human service belongs.
v human_service_app_short_name - the short name of the IBM Business Process
Manager human service application.
v icon - optional, an offering can have an icon assigned that is displayed inside
the Self-Service Catalog.
v id - the ID of the offering.
v implementation_type - the two possible values are 'ibm_bpm_process and
script.
v name - the name of the offering.
v operation_type - the only possible value is "service".
v ownerid - the owner of the user who triggered the offering.
v process - the name of the IBM Business Process Manager process bound to the
offering.
v process_app_id - the ID of the IBM Business Process Manager application in
which the process is defined.
v process_app_name - the name of the IBM Business Process Manager application
in which the process is defined.
Chapter 11. Reference

943

v process_app_short_name - the short name of the IBM Business Process Manager

process application.
v updated - the time when the self-service offering was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This value
is numeric and is automatically generated by the product.
{
"isbuiltin": 0,
"icon": "Web Category Icon:ge100_webcatalog_24",
"name": "Bucket",
"id": 8,
"description": ""
},
{
"isbuiltin": 0,
"icon": "Cloud Category Icon:ge100_virtualfabriccatalog_24",
"name": "Help Desk",
"id": 3,
"description": ""
},

Get the details of a single category:

Use this REST call to get the details of a single category.
Available HTTP method
Table 135. Get the details of a single category REST API call
HTTP method

GET

URL pattern

/resources/automationcategories/8

Response

The response of the server contains the specified offering. It has the
following set of attributes:
{
category:
created:
description:
human_service:
human_service_app_id:
human_service_app_name:
human_service_app_short_name:
icon:
id:
implementation_type:
name:
operation_type:
ownerid:
process:
process_app_id:
process_app_name:
process_app_short_name:
updated:
}

An entry has the following attributes:

v category - optional, the category to which the offering belongs.
v created - the creation time of the self-service offering, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric and
is automatically generated by the product.
v description - optional, a short description of the offering.

944

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v human_service - optional, the URL of an IBM Business Process Manager human

service (coach), a user interface to provide user input.
v human_service_app_id - optional, depending on the human_service attribute, the
ID of the IBM Business Process Manager application to which the human service
belongs.
v human_service_app_name - optional, depends on if the human_service attribute is
set, the name of the IBM Business Process Manager application to which the
human service belongs.
v human_service_app_short_name - the short name of the IBM Business Process
Manager human service application.
v icon - optional, an offering can have an icon assigned that is displayed inside
the Self-Service Catalog.
v id - the ID of the offering.
v implementation_type - the two possible values are 'ibm_bpm_process and
script.
v name - the name of the offering.
v operation_type - the only possible value is "service".
v ownerid - the owner of the user who triggered the offering.
v process - the name of the IBM Business Process Manager process bound to the
offering.
v process_app_id - the ID of the IBM Business Process Manager application in
which the process is defined.
v process_app_name - the name of the IBM Business Process Manager application
in which the process is defined.
v process_app_short_name - the short name of the IBM Business Process Manager
process application.
v updated - the time when the self-service offering was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This value
is numeric and is automatically generated by the product.
{
"isbuiltin": 0,
"icon": "Web Category Icon:ge100_webcatalog_24",
"name": "Bucket",
"id": 8,
"description": ""
}

Update a category:
Use this REST call to update a category.
Available HTTP method
Table 136. Update a category REST API call
HTTP method

PUT

URL pattern

/resources/automationcategories/8

Response

The self-service offering is updated.

Structure of request body:

{

"<attribute>": "<attribute_value>" }

Chapter 11. Reference

945

{
"description": "new description of category 8"
}

Delete a category:
Use this REST call to delete a category.
Available HTTP method
Table 137. Delete a category REST API call
HTTP method

DELETE

URL pattern

/resources/automationcategories/8

Response

The self-service offering is deleted.

Task engine REST API:

You can use this set of REST API calls to interact with role parameters of a specific
server instance.
Task engine API V1:
The following section describes JSON Formats and instances for task engine API
V1.
JSON Formats
Task Response
{
"updated_iso" : "2014-03-31T13:05:14+0200",
"description_message" : "The process is complete.",
"domain" : "Default",
"created" : 1396263830875,
"error" : {
"resourceBundle" : "com.ibm.orchestrator.messages.orchestratormessages",
"message" : null,
"messageKey" : "BPM_PROCESS_COMPLETE",
"args" :
[
"3"
]
},
"user" : "ksadmin",
"parm" : {
.....
},
"created_iso" : "2014-03-31T13:03:50+0200",
"status_localized" : "Completed",
"error_message" : "CTJCO0002I: Business process instance 3 completed successfully.",
"status" : "COMPLETED",
"eventTopic" : "com/ibm/orchestrator/serviceinstance/plan/ibm_bpm_process",
"delayInSeconds" : 30,
"project" : "admin",
"id" : "1003",
"updated" : 1396263914896,
"description" : {
"resourceBundle" : "com.ibm.orchestrator.messages.orchestratormessages",
"message" : null,
"messageKey" : "PROCESS_COMPLETE",
"args" :

946

IBM Cloud Orchestrator 2.4.0.2: User's Guide

[
]
}
}

Tasks Response
[ Task Response 1,....., Task Response n]
GET: Get all tasks
URL method
/kernel/tasks
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
200
Response
Tasks Response
GET: Get the task with a given id
URL method
/kernel/tasks/{id}
Accepts
*/*
Content-Type
application/JSON
Normal Response Codes
200
Response
Task Response
List all currently running and recently completed tasks:
Use this REST API method to list all currently running tasks and the tasks that
were completed not longer than two weeks before.
Available HTTP method
Table 138. List all currently running and recently completed tasks REST API call
HTTP method

GET

URL pattern

https://hostname/kernel/tasks/

Response

List all the currently running and recently completed tasks.

[<task>]

Return values

v 200 - OK
v 500 - Internal Server Error

Structure of the query string:

Chapter 11. Reference

947

v tasks - a comma-separated list of task objects.

Get entries for a specific task:
Use this REST call to retrieve information about an active task with an indicated
ID.
Available HTTP method
Table 139. Get information about a specific task
HTTP method

GET

URL pattern

https://hostname/kernel/tasks/{id}

Response

The following parameters of the task are retrieved:

{
updated_iso:
description_message:
message:
created:
error:
parm: {
plan:
}
status_localized:
created_iso:
error_message:
internal status:
status:
eventTopic:
delayInSeconds:
id:
updated:
description: {
resourceBundle:
message:
messageKey:
args:
}
}

Return values

v 200 - OK
v 401 - The currently logged in user is not authorized to retrieve
the task. Only Administrators and creators of the task can see
the task.
v 404 The task does not exist.

The parameters of the response:

v updated_iso - the last update to the task in ISO8601 format.
v description_message - G11N enabled information about the function of the task.
v message - gives current status, which is displayed to the end user.
v created - the time at which the task was created in java timestamp format.
v error - a structured object containing an error message if any exists.
v parm - a free-form key-value pair object containing all the use-cases specific
parameters. It can contain the following parameter:
plan - contains the self-service offering that was used to create the task. A
plan object is only available for tasks that complete self-service offerings.
v status_localized - a G11N enabled status for the task.

948

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v internal status - one of the following: NEW, QUEUED, RUNNING,

SUSPENDED, FAILING, FAILED, COMPLETING, COMPLETED, CANCELING,
CANCELED.
v eventTopic - identifies the handler that is used to complete the task.
v description - contains the internal representation for the description_message
message.
The following listing shows a sample response that can be obtained via the REST
call:
{
"updated_iso" : "2012-08-24T14:06:04+0200",
"description_message" : "Invoke operation \"Report Problem\" using input parameters entered
through a human service.",
"message" : "The operation was started successfully. For status, check <a
href=\"/dashboard/appliance/tasks/#e9960f9a-c8cf-499c-8279-73d3a9fbf49e\">the
task</a> in the task queue."
"created" : 1345809964681,
"error" : null,
"parm" : { "plan" : { "human_service" : "Sample_ReportProblem",
"human_service_app_name" : "SCOrchestrator_Toolkit",
"implementation_type" : "ibm_bpm_process",
"human_service_app_short_name" : "SCOTLKT",
"created" : 1345809954675,
"process_app_id" : "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"name" : "Report Problem",
"ownerid" : 1,
"process" : "Sample_AssignProblem",
"operation_type" : "service",
"human_service_app_id" : "2066.596706e1-2e92-4fb1-a2dd-e0e4bdc4f7fc",
"process_app_name" : "SCOrchestrator_Toolkit",
"event" : null,
"updated" : 1345809954675,
"id" : 4,
"process_app_short_name" : "SCOTLKT",
"description" : "",
"category" : "",
"apply_to_all_pattern" : 0
}
},
"status_localized" : "New",
"created_iso" : "2012-08-24T14:06:04+0200",
"error_message" : null,
"status" : "NEW",
"eventTopic" : "com/ibm/orchestrator/serviceinstance/plan/ibm_bpm_process",
"delayInSeconds" : 0,
"id" : "e9960f9a-c8cf-499c-8279-73d3a9fbf49e",
"updated" : 1345809964685,
"description" : { "resourceBundle" : "com.ibm.orchestrator.messages.orchestratormessages",
"message" : "HS_OPERATION_INVOCATION",
"messageKey" : "HS_OPERATION_INVOCATION",
"args" : [ "Report Problem" ]
}
}

Chapter 11. Reference

949

Workload Deployer REST API

You can use this set of REST API calls to interact with the Workload Deployer
component.

Environment profiles REST API

You can use the representational state transfer (REST) application programming
interface (API) to manage environment profiles.

Available HTTP Methods

Table 140. REST API for environment profiles
HTTP
Method
GET

POST

URI Pattern

Date Format

/resources/
environmentProfiles

application/json

/resources/
environmentProfiles

application/json

Success Codes
200

201

Error Codes

403
Returns the list of
environment profiles
that are visible to the
client.

This code is returned

if the requester does
not have access to
list environment
profiles.

500

This code is returned

if the IBM Cloud
Orchestrator
encountered an
internal error while
processing the
request.

500

This code is returned

if IBM Cloud
Orchestrator
encountered an
internal error while
processing the
request.

The resources has

been created
successfully.

An environment profile has the following attributes:

created
Specifies the creation time of the environment profile, represented as the
number of milliseconds since midnight, January 1, 1970 UTC. This value is
numeric and is automatically generated by the product.
currentmessage
Specifies the message associated with the current status of the environment
profile. This is an 8 character string value that is generated by the product.
currentmessage_text
Specifies the textual representation of currentmessage. This is a string
representation of currentmessage in the preferred language of the requester
and is automatically generated by the product.
currentstatus
Specifies a string constant representing the current status of the
environment profile. This is an 8 character string value is automatically
generated by the product.
currentstatus_text
Specifies the textual representation of currentstatus. This is a string

950

IBM Cloud Orchestrator 2.4.0.2: User's Guide

representation of currentstatus in the preferred language of the requester

and is automatically generated by the product.
description
Specifies the description of the environment profile. This field is a string
value with a maximum of 1024 characters.
domainname
Specifies the name of the domain.
domainou
Specifies the organizational unit where the computer account is stored.
domainpassword
Specifies the password of the domain user.
domainusername
Specifies the user name that is authorized to add a computer account the
domain.
environment
Specifies the environment the profile represents. Valid values from 0 to 7
are:
deployer.environmentprofile.ALL_ENVIRONMENT
deployer.environmentprofile.DEVELOPMENT_ENVIRONMENT
deployer.environmentprofile.TEST_ENVIRONMENT
deployer.environmentprofile.QUALITY_ASSURANCE_ENVIRONMENT
deployer.environmentprofile.PERFORMANCE_ENVIRONMENT
deployer.environmentprofile.RESEARCH_ENVIRONMENT
deployer.environmentprofile.PRODUCTION_ENVIRONMENT
deployer.environmentprofile.PRE_PRODUCTION_ENVIRONMENT

environment_text
Specifies the textual representation of environment. This is a string
representation of environment in the preferred language of the requester
and is automatically generated by the product.
id

Specifies the ID of the environment profile. This numeric value is

automatically generated by the product.

kmsipaddress
Specifies the IP address of the KMS server in your environment.
kmsport
Specifies the port used for KMS service.
name

Specifies the display name associated with this environment profile. This
field contains a string value with a maximum of 1024 characters.

owner Specifies the uniform resource identifier (URI) of the user that owns this
environment profile. The URI is relative and should be resolved against the
URI of the owner.
platform
Specifies the type of hypervisors this environment profile supports on
deployments. Valid values are ESX, PowerVM, and zVM.
updated
Specifies the time the environment profile was last updated, represented as
the number of milliseconds since midnight, January 1, 1970 UTC. This
value is numeric and is automatically generated by the product.
vmname_pattern
Specifies the pattern used to generate virtual machine names.
Chapter 11. Reference

951

GET /resources/environmentProfiles example

[
{
"clouds": [
{
"cloud": "/resources/clouds/1",
"alias": "t",
"ipGroups": [
{
"alias": "t",
"ipGroup": "/resources/ipGroups/1"
}
]
}
],
"created": 1285348986268,
"currentmessage": "RM25008",
"currentmessage_text": "Environment profile can now be use for deployments"
A virtual system instance has the following attributes:
"currentstatus": "RM01001",
"currentstatus_text": "Defined",
"description": "",
"environment": 0,
"environment_text": "All",
"id": 1,
"ipsource": 0,
"ipsource_text": "Workload Deployer",
"name": "test",
"owner": "/resources/users/1",
"platform": "OpenStack",
"updated": 1285352832052,
"vmname_pattern": "",
},
{
"clouds": [
{
"cloud": "/resources/clouds/1",
"alias": "t",
"ipGroups": [
{
"alias": "t",
"ipGroup": "/resources/ipGroups/1"
}
]
}
],
"created": 1285348986268,
"currentmessage": "RM25008",
"currentmessage_text": "Environment profile can now be use for deployments"
A virtual system has the following attributes:
"currentstatus": "RM01001",
"currentstatus_text": "Defined",
"description": "",
"environment": 0,
"environment_text": "All",
"id": 2,
"ipsource": 0,
"ipsource_text": "Workload Deployer",
"name": "test2",
"owner": "/resources/users/1",
"platform": "OpenStack",
"updated": 1285352832052,
"vmname_pattern": "",
}
]

952

IBM Cloud Orchestrator 2.4.0.2: User's Guide

See the description of GET /resources/virtualsystems/{id} for attribute details.

GET /resources/environmentProfiles/{id} example

{
"clouds": [
{
"cloud": "/resources/clouds/1",
"alias": "t",
"ipGroups": [
{
"alias": "t",
"ipGroup": "/resources/ipGroups/1"
}
]
}
],
"created": 1285348986268,
"currentmessage": "RM25008",
"currentmessage_text": "Environment profile can now be use for deployments"
A virtual system has the following attributes:
"currentstatus": "RM01001",
"currentstatus_text": "Defined",
"description": "",
"environment": 0,
"environment_text": "All",
"id": 2,
"ipsource": 0,
"ipsource_text": "Workload Deployer",
"name": "test2",
"owner": "/resources/users/1",
"platform": "OpenStack",
"updated": 1285352832052,
"vmname_pattern": "",
}

POST /resources/environmentProfiles example

Request JSON:
{
"platform":"OpenStack","environment":0,"description":"Sample description","name":"envProfileName"
}

Log viewer manager REST API

You can use the representational state transfer (REST) application programming
interface (API) to manage Log Viewer Manager.

Chapter 11. Reference

953

Available HTTP Methods

Table 141. REST API for LogViewerMgr
HTTP
Method

URI Pattern

POST

/resources/logViewerMgr

GET

Data Format

/resources/logViewerMgr/
{id}

Success Codes
This code is
returned if log
viewing for the
specified log file
was successfully
initialized. The
Location header
in the response
contains a URL
that can be
queried to view
contents of the
log file.

403

This code is
returned if the
requester has not
been assigned the
admin role.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

200

This code is
returned if
content from the
log file is
included in the
output.

403

This code is
returned if the
requester has not
been assigned the
admin role.

404

204

This code is
returned if the
specified
startingPoint and
lineCount do not
include any
content from the
log file.

This code is
returned if the
specified log
viewing has not
been initialized
correctly.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

200

application/json

Error Codes

POST /resources/logViewerMgr example

This REST API call initializes log viewing for a specific log file. The Location
header in the response contains a URL that can be subsequently queried to fetch
new contents of the specified file.
Request:
POST /resources/logViewerMgr?logfile=trace/trace.log

Response headers:
Location: https://myproduct.mycompany.com/resources/logViewerMgr/trace_%5E_trace.log

GET /resources/logViewerMgr/{id} example

Request:
GET /resources/logViewerMgr/trace_%5E_trace.log?startingPoint=0&lineCount=3

954

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Response JSON:
{
"NEXT_CHUNK": 214,
"TAIL_CONTENT": "************ Start Display Current Environment ************
Workload Deployer version number is 1.0.0.1-11776
Java Version = J2RE 1.6.0 IBM J9 2.4 Linux x86-32 jvmxi3260-20090215_29883
(JIT enabled,AOT enabled)"
}

The TAIL_CONTENT entry in the response contains contents of the log file; the
NEXT_CHUNK value in the response can be used as the startingPoint in the next
request to retrieve subsequent content from the log file.
Related tasks:
REST API reference on page 867
The representational state transfer (REST) application programming interface (API)
is provided by IBM Cloud Orchestrator.

Logging REST API

Use REST APIs to log application monitoring results.
The following tasks can be completed using the REST API.

List all the logs on a specific virtual machine

GET /resources/virtualApplications/{virtual_application_instance_id}/logs/virtualMachines/
{virtual_machine_id}
Table 142. List all the logs on a specific virtual machine
Example URL

https://localhost/resources/virtualApplications/d-65d297159063-436d-8593-d5218208f8aa/logs/virtualMachines/
Web_Application-was.11319468974926

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example (lists of files for different roles):

{
"OS":["/var/log/brcm-iscsi.log",
"/var/log/cron",
"/var/log/messages",
"/var/log/secure",
"/var/log/acpid",
"/var/log/dmesg",
"/var/log/yum.log",
"/var/log/wtmp",
"/var/log/spooler",
"/var/log/maillog",
"/var/log/boot.log"
],
"WAS":["/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1/SystemErr.log",
"/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1/native_stderr.log",
"/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1/native_stdout.log",
"/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1/SystemOut.log",
"/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/ffdc/ffdc.3819090375058668621.txt",
"/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/ffdc/FfdcSummary.txt",
"/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/ffdc/ffdc.6804038344002622019.txt"
],
"IWD Agent":["/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.MONITORING/trace.log",

Chapter 11. Reference

955

"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.MONITORING/console.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.WAS/trace.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.WAS/console.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.SSH/trace.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.SSH/console.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.AGENT/trace.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/
Web_Application-was.11319468974926.AGENT/console.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/console.log.0",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/trace.log.0",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/trace.log.2",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/install/trace.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/install/console.log",
"/opt/IBM/maestro/agent/usr/servers/Web_Application-was.11319468974926/logs/trace.log.1",
"/0config/0config.log"
]
}

Get the content of a specific log file

GET

/resources/virtualApplications/{virtual_application_instance_id}/logs/virtualMachines/
{virtual_machine_id} /{log_absolute_path}

Table 143. Get the content of a specific log file

Example URL

https://localhost/resources/virtualApplications/d-65d297159063-436d-8593-d5218208f8aa/logs/virtualMachines/
Web_Application-was.11319468974926/opt/IBM/maestro/
agent/usr/servers/Web_Application-was.11319468974926/
logs/Web_Application-was.11319468974926.WAS/trace.log

Request headers

bytes={start}-{end}

For example, bytes=0-500.

Specify the byte range of the
log file to get. If the bye
range is not set, entire log file
is gotten.

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
[2011-10-24 16:03:53,756]
[2011-10-24 16:03:53,757]
simple under context root
[2011-10-24 16:05:53,998]
to RUNNING

956

IBM Cloud Orchestrator 2.4.0.2: User's Guide

WAS/start.py 47377699650752 pid=23164 INFO WAS: 8.0.0.1

WAS/start.py 47377699650752 pid=23164 INFO Installing WAR file
/simple
WAS/start.py 47377699650752 pid=23164 INFO set WAS role status

Monitoring REST API

Use REST APIs for applications monitoring tasks.
The following tasks can be completed using the REST API:

Get the overall monitoring status for a given virtual application

instance
GET /resources/virtualApplications/{virtual_application_instance_id}/monitoring
Table 144. Get the overall monitoring status of a given virtual application
Example URL

https://localhost/resources/virtualApplications/d-65d297159063-436d-8593-d5218208f8aa/monitoring

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
{
"SERVERS":[{
"vm_id":"1",
"vm_uuid":"4217cc6c-0d82-575d-c983-4c76d221ded5",
"hypervisor_uuid":"52e11db5-2c40-e011-ae1b-00215e5d6968",
"private_ip":"192.0.2.208",
"server_name":"Web_Application-was.11319468974926",
"public_hostname":"ipas-vm-071-208.purescale.raleigh.ibm.com",
"state":"RUNNING",
"time_stamp":1319471278884,
"vm_name":"Web_Application-was.11319468974926",
"deployment_id":"d-65d29715-9063-436d-8593-d5218208f8aa",
"hypervisor_hostname":"192.0.2.31",
"availability":"NORMAL",
"public_ip":"192.0.2.208"
}
],
"application":{
"connectors":[],
"workload":"TRUE",
"application_name":"simple",
"application_id":"a-0f5985ee-d5f2-4512-b9ae-e4934a8e3ea0"
},
"ROLETYPES":[{
"roleType":"AGENT",
"template":"Web_Application-was",
"availability":"NORMAL"
},
{
"roleType":"SSH",
"template":"Web_Application-was",
"availability":"NORMAL"
},
{
"roleType":"MONITORING",
"template":"Web_Application-was",
"availability":"NORMAL"
},
{
"roleType":"WAS",
Chapter 11. Reference

957

"template":"Web_Application-was",
"availability":"NORMAL"
}
],
"deployment":{
"time_stamp":1319472359280,
"platform":"ESX",
"env_profile_id":"1",
"cloud_group_id":"1",
"deployment_name":"simple",
"deployment_id":"d-65d29715-9063-436d-8593-d5218208f8aa",
"availability":"NORMAL",
"deployment_status":"RUNNING",
"vs_id":"1"
},
"version":2,
"ROLES":[{
"time_stamp":1319472359280,
"state":"RUNNING",
"private_ip":"192.0.2.208",
"role_type":"WAS",
"role_name":"Web_Application-was.11319468974926.WAS",
"display_metrics":true,
"server_name":"Web_Application-was.11319468974926",
"pattern_version":"2.0",
"pattern_type":"webapp",
"availability":"NORMAL"
}
],
"appliance":{
"runtime_env":"vm",
"appliance_type":"unknown",
"appliance_group":"",
"appliance_name":"",
"appliance_id":"unknown"
}
}

Get the virtual machine monitoring status for a given virtual

application instance
GET /resources/virtualApplications/{virtual_application_instance_id}/monitoring/servers
Table 145. Get the virtual machine monitoring status for a given virtual application instance
Example URL

https://localhost/resources/virtualApplications/d-65d297159063-436d-8593-d5218208f8aa/monitoring/servers

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
[{
"vm_id":"1",
"vm_uuid":"4217cc6c-0d82-575d-c983-4c76d221ded5",
"hypervisor_uuid":"52e11db5-2c40-e011-ae1b-00215e5d6968",
"private_ip":"192.0.2.208",
"server_name":"Web_Application-was.11319468974926",
"public_hostname":"ipas-vm-071-208.purescale.raleigh.ibm.com",
"state":"RUNNING",

958

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"time_stamp":1319471278884,
"vm_name":"Web_Application-was.11319468974926",
"deployment_id":"d-65d29715-9063-436d-8593-d5218208f8aa",
"hypervisor_hostname":"192.0.2.31",
"availability":"NORMAL",
"public_ip":"192.0.2.208"
}
]

Get the middleware monitoring status for a given virtual application

instance
GET /resources/virtualApplications/{virtual_application_instance_id}/monitoring/roles
Table 146. Get the middleware monitoring status for a given virtual application instance
Example URL

https://localhost/resources/virtualApplications/d-65d297159063-436d-8593-d5218208f8aa/monitoring/role

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
[{
"time_stamp":1319472359280,
"state":"RUNNING",
"private_ip":"192.0.2.208",
"role_type":"WAS",
"role_name":"Web_Application-was.11319468974926.WAS",
"display_metrics":true,
"server_name":"Web_Application-was.11319468974926",
"pattern_version":"2.0",
"pattern_type":"webapp",
"availability":"NORMAL"
}
]

Get virtual machine level monitoring metrics for a specific virtual

machine
GET /resources/virtualApplications/{virtual_application_instance_id}/monitoring/servers/
{virtual_machine_id}/metrics/
Table 147. Get virtual machine level monitoring metrics of a specific virtual machine
Example URL

https://localhost/resources/virtualApplications/d-65d297159063-436d-8593-d5218208f8aa/monitoring/servers/
Web_Application-was.11319468974926/metrics/

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
Chapter 11. Reference

959

{
"MEMORY":{
"memory_used_percent":9.97,
"time_stamp":1319537926447,
"memory_total":2368
},
"CPU":{
"time_stamp":1319537926447,
"busy_cpu":3.73
},
"DISK":{
"blocks_reads_per_second":642,
"time_stamp":1319537917993,
"blocks_written_per_second":10441
},
"NETWORK":{
"time_stamp":1319537917993,
"megabytes_received_per_sec":0.001,
"megabytes_transmitted_per_sec":0.002
}
}

Get middleware level monitoring metrics of a specific middleware

GET /resources/virtualApplications/{virtual_application_instance_id}/monitoring/roles/
{middleware_id}/metrics/
Table 148. Get middleware level monitoring metrics of a specific middleware
Example URL

https://localhost/resources/virtualApplications/d-65d297159063-436d-8593-d5218208f8aa/monitoring/roles/
Web_Application-was.11319468974926.WAS/metrics/

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
{
"WAS_WebApplications":{
"time_stamp":1319538432348,
"max_service_time":0,
"min_service_time":0,
"service_time":0,
"request_count":0
},
"WAS_TransactionManager":{
"time_stamp":1319538432348,
"rolledback_count":0,
"active_count":0,
"committed_count":12
},
"WAS_JDBCConnectionPools":{
"time_stamp":1319538432348,
"max_percent_used":0,
"min_percent_used":0,
"percent_used":0,
"wait_time":0,
"min_wait_time":0,
"max_wait_time":0
},
"WAS_JVMRuntime":{

960

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"time_stamp":1319538432348,
"jvm_heap_used":51.387638,
"used_memory":77583,
"heap_size":150976
}
}

Pattern types REST API

You can use the REST API to manage your virtual application pattern types.
The following tasks can be completed using the REST API.

List all pattern types with version format "vr" or "vmf"

GET /resources/patternTypes/?version={format}
vr is to get pattern types with vr version format, e.g. 1.0
vrmf is to get pattern types with vrmf version format, e.g. 1.0.0.0
Table 149. List all pattern types with version format "vr" or "vmf" details
Example URL

https://localhost/resources/patternTypes/?version=vr

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
[
{
"license": {
"type": "PVU",
"pid": "5725E00"
},
"status": "avail",
"licenses": [
"https://192.0.2.45:9444/storehouse/admin/patterntypes/dbaas/1.0/licenses/"
],
"shortname": "dbaas",
"version": "1.0",
"name": "DBaaS Pattern Type",
"description": "IBM Workload Deployer Pattern Type for DBaaS",
"url": "https://192.0.2.45:9444/storehouse/admin/patterntypes/dbaas/1.0/"
},
...
]

Create a pattern type

POST /resources/patternTypes
Table 150. Create a pattern type details
Example URL

https://localhost/resources/patternTypes/

Request content-type

application/json

Request example

Request body: tgz File

Response header location

https://localhost/resources/patternTypes/
{patternTypesName}/{version_vrmf}

Response code

201

Created successfully
Chapter 11. Reference

961

Table 150. Create a pattern type details (continued)

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

List detail information of one pattern type

GET /resources/patternTypes/{patternTypeName}/{version}
Table 151. List detail information of one pattern type
Example URL

https://localhost/resources/patternTypes/dbaas/1.0

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
{
"license": {
"type": "PVU",
"pid": "5725E00"
},
"status": "avail",
"licenses": [
"https://192.0.2.45:9444/storehouse/admin/patterntypes/dbaas/1.0/licenses/"
],
"shortname": "dbaas",
"version": "1.0",
"name": "DBaaS Pattern Type",
"description": "IBM Workload Deployer Pattern Type for DBaaS",
"url": "https://192.0.2.45:9444/storehouse/admin/patterntypes/dbaas/1.0/"
}

List plugin list of one pattern type

GET /resources/patternTypes/{patternTypeName}/{version}/plugins
Table 152. List plugin list of one pattern type details
Example URL

https://localhost/resources/patternTypes/dbaas/1.0/
plugins

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:

962

IBM Cloud Orchestrator 2.4.0.2: User's Guide

[
"firewall/1.0.0.0",
"webapp-license/1.0.0.0",
"tds/1.0.0.0",
"agent/1.0.0.0",
"logbackup/1.0.0.0",
"monitoring/1.0.0.0",
"ssh/1.0.0.0",
...
]

Accept the license agreement of a pattern type

PUT /resources/patternTypes/{patternTypeName}/{version_vr}/
Table 153. Accept the license agreement of a pattern type
Example URL

https://localhost/resources/patternTypes/webapp/1.0/

Response content-type

application/json

Request example

Request body:
{
"status": "accepted"
}
Valid status includes accepted, avail, and unavail.

Response body

{
"status": "accepted"
}

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Delete a pattern type

DELETE /resources/patternTypes/{patternTypeName}/{version_vrmf}
Table 154. Delete a pattern type details
Example URL

https://localhost/resources/patternTypes/webapp/1.0.0.0

Response content-type

application/json

Response example

true or false

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Chapter 11. Reference

963

Plug-ins REST API

You can use the REST API to manage your plug-ins.
The following tasks can be completed using the REST API.

Retrieve all plug-ins

GET /resources/plugins/
Table 155. Retrieve all plug-ins details
Example URL

https://localhost/resources/plugins/

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
[
{
"content_type": "application/json",
"last_modifier": "cbadmin",
"create_time": "2011-02-23T13:35:55Z",
"enabled": true,
"last_modified": "2011-02-23T13:38:48Z",
"access_rights": {
"cbadmin": "F",
"_group_:Everyone": "R"
},
"content_md5": "6DDE51DF49D718372BA1EBAFF3E71410",
"name": " waswmqq/1.0.0.0",
"creator": "cbadmin"
},
{
"content_type": "application/json",
"last_modifier": "cbadmin",
"create_time": "2011-02-23T13:36:08Z",
"enabled": true,
"last_modified": "2011-02-23T13:36:09Z",
"access_rights": {
"cbadmin": "F",
"_group_:Everyone": "R"
},
"content_md5": "83F1AAD5EFCEBB89B835A3CD2C89D6A5",
"name": "webservice/1.0.0.0",
"creator": "cbadmin"
},
...
]

Create a plug-in
POST /resources/plugins/
Table 156. Create a plug-in details

964

Example URL

https://localhost/resources/plugins/

Request content-type

application/binary

Request example

Request body: the tgz file, for example,firewall-1.0.0.0.tgz

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 156. Create a plug-in details (continued)

Response header location

https://localhost/resources/plugins/firewall/1.0.0.0

Response code

201

Created successfully

401

The user is not authorized to

perform this action.

403

Access forbidden

409

Conflict

500

Unexpected error

Response example:
{
"artifacts": "https://192.0.2.84:9444/storehouse/admin/plugins/firewall/1.0.0.0/",
"enabled": true,
"plugin": "https://192.0.2.84:9443/services/plugins/firewall/1.0.0.0",
"ETag": "\"177436A9E6C767F309C2D1D8158F8587-2011-05-14T14:13:25Z-1305382405351\"",
"patterntypes": null,
"name": "firewall/1.0.0.0"
}

Delete a plug-in
DELETE /resources/plugins/{plugin_name}/{version}
Table 157. Delete a plug-in details
Example URL

https://localhost/resources/plugins/firewall/1.0.0.0

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

409

Conflict

500

Unexpected error

Retrieve plug-in information

GET /resources/plugins/{plugin_name}/{version}
Table 158. Retrieve plug-in information details
Example URL

https://localhost/resources/plugins/firewall/1.0.0.0

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

404

The Plug-in specified by the

{plugin_name} is not found.

500

Unexpected error

Response example:

Chapter 11. Reference

965

{
"CreateTime": "2011-05-14T14:13:25Z",
"Content-MD5": "177436A9E6C767F309C2D1D8158F8587",
"name": "firewall/1.0.0.0",
"AccessRights": {
"cbadmin": "F",
"_group_:Everyone": "R"
},
"Creator": "cbadmin",
"LastModifier": "cbadmin",
"Content-Type": "application/json",
"LastModified": "2011-05-14T14:13:25Z"
}

Shared services REST API

Use REST APIs to complete tasks related to the shared services pattern.
The following tasks can be completed using the REST API.

List all patterns of shared services

GET /resources/sharedServices/
Table 159. List all patterns of shared services
Example URL

https://localhost/resources/sharedServices

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
[
{
"last_modifier": "cbadmin",
"content_type": "application/json",
"service_version": "1.0",
"app_storehouse_base_url": "https://192.0.2.130:9444/storehouse/user/applications/a-098b
587d-4f62-4ec6-a753-983d37db804f/",
"app_name": "ITM_SERVICE_LABEL",
"patterntype": "foundation",
"creator": "cbadmin",
"service_type": "External",
"service_supported_clients": "[0.0,1.0]",
"create_time": "2011-09-19T11:03:47Z",
"last_modified": "2011-09-19T11:03:47Z",
"access_rights": {
"cbadmin": "F",
"_group_:Everyone": "R"
},
"app_mgmtserver_url": "https://192.0.2.130:9443/services/applications/a-098b587d-4f6
2-4ec6-a753-983d37db804f",
"version": "2.0",
"content_md5": "93DABBAB77E0BBE9571E81FF1133F807",
"app_type": "service",
"app_id": "a-098b587d-4f62-4ec6-a753-983d37db804f",
"description": "ITMEXT_SERVICE_DESC",

966

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"Collection": "."
},
...
]

Deploy shared services into a cloud group

Important: After a shared services pattern is deployed, an instance is generated of
shared services pattern. The instance is a virtual application instance, therefore you
can use the virtual application instance REST API to get the details.
POST /resources/sharedServices/<id>/virtualApplications
Table 160. Deploy a shared services pattern into a cloud group
Example URL

https://localhost/resources/sharedServices/
a-6d29ddbc-7005-469a-878 f-b467ff57dd3f
/virtualApplications

Response content-type

application/json

Response code

201

OK

400

Invalid request parameter.

401

The user is not authorized to

perform this action.

409

Instance exists in the cloud.

500

Unexpected error

Response example:
{
"deployment_name":"PROXY",
"ssh_keys":[""],
"model":{
"model":{
"servicename":"proxy",
"nodes":[
{
"attributes":{
"numberOfELBInstances":2
},
"type":"PROXY",
"id":"sharedservice",
"groups":{}
}
],
"serviceversion":"2.0",
"version":"2.0",
"servicedisplayname":"proxy",
"app_type":"service",
"links":[],
"patterntype":"foundation",
"name":"PROXY",
"description":"ELB proxy Service",
"servicesupportedclients":"2.0"
}
},
"cloud_group":"1",
"ip_version":"IPv4"
}

Chapter 11. Reference

967

Version REST API

You can use the representational state transfer (REST) application programming
interface (API) to obtain version information about IBM Cloud Orchestrator.

Available HTTP Methods

Table 161. REST API for versions
HTTP
Method

URI Pattern

Data Format

GET

/resources/version

application/json

Success Codes
200

Returns information
about the Workload
Deployer component
version installed in
IBM Cloud
Orchestrator. See the
example for a
sample of the data
returned.

Error Codes
None.

The version information is returned as a map containing the following keys:

version
The version of the Workload Deployer component, as a 4-part version
number followed by a hyphen and a build identifier.

GET /resources/version example

{
"version": "3.0.0.0-32058"
}

Related tasks:
REST API reference on page 867
The representational state transfer (REST) application programming interface (API)
is provided by IBM Cloud Orchestrator.

Virtual appliance instances REST API

You can use the representational state transfer (REST) application programming
interface (API) to manage virtual appliance instances. These images are the virtual
machines that are not created by IBM Cloud Orchestrator but that were taken over.

968

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Available HTTP Methods

Table 162. REST API for VirtualApplianceInstances
HTTP
Method
GET

GET

URI Pattern

Data Format

/resources/
virtualApplianceInstances

application/json

Success Codes
200

/resources/
application/json
200
virtualApplianceInstances/{id}

Error Codes

403
Returns the list
of virtual
appliance
instances that are
visible to the
client.

Returns the
virtual appliance
instance
associated with
the given ID.

This code is
returned if the
requester does
not have access
to list virtual
appliance
instances.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403

This code is
returned if the
requester does
not have access
to the requested
virtual appliance
instance.

404

This code is
returned if the
requested virtual
appliance
instance is not
defined.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

Chapter 11. Reference

969

Table 162. REST API for VirtualApplianceInstances (continued)

HTTP
Method
PUT

URI Pattern

Data Format

Success Codes

/resources/
application/json
200
virtualApplianceInstances/{id}

DELETE

/resources/
virtualApplianceInstances/{id}

204

400

This code is
returned if there
are problems
parsing the JSON
data in the
request.

403

This code is
returned if the
requester does
not have
permission to
update the
virtual appliance
instance.

404

This code is
returned if the
request
references a
resource that is
not defined.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403
The virtual
appliance
instance has been
deleted.

This code is
returned if the
requester does
not have
permission to
delete the virtual
appliance
instance.

404

This code is
returned if the
requested virtual
appliance
instance is not
defined.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

The virtual
appliance
instance was
successfully
updated. The
response body
contains a JSON
representation of
the current state
of the virtual
appliance.

A virtual appliance instance has the following attributes:

970

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Error Codes

created
Specifies the creation time of the virtual appliance instance, represented as
the number of milliseconds since midnight, January 1, 1970 UTC.
currentmessage
Specifies the message associated with the current status of the virtual
appliance instance. This field contains an 8 character string value that is
generated by the product.
currentstatus
Specifies a string constant representing the current status of the virtual
appliance instance. This field contains an 8 character string value that is
generated by the product.
currentstatus_text
Specifies the textual representation of currentstatus. This is a string
representation of currentstatus in the preferred language of the requester
and is automatically generated by the product.
desiredstatus
Specifies the desired status of the virtual appliance instance. Setting this
value causes IBM Cloud Orchestrator to initiate the steps needed to get the
virtual system appliance to this state. This value is an 8 character string
value and it can be set to one of the following values: RM01006 (started) or
RM01011 (stopped).
id

Specifies the ID of the virtual appliance instance. This numeric value is

automatically generated by the product.

name

Specifies the display name associated with this virtual appliance instance.
This string contains a string value with a maximum of 1024 characters.

type

Is always set to APPLIANCE.

updated
Specifies the time that the virtual appliance instance was last updated,
represented as the number of milliseconds since midnight, January 1, 1970
UTC.

GET /resources/virtualApplianceInstances example

[
{
"currentstatus_text": "Stopped",
"elasticstatus": "",
"name": "My image",
"desiredstatus": "",
"ownerid": 40,
"restartstage": 0,
"environmentprofileid": null,
"elasticmessage": "",
"currentmaintenanceid": null,
"id": 61,
"ipasmastergroupuuid": null,
"deploymentid": null,
"offeringid": -1,
"iptype": "IPv4",
"mode": "",
"priority": 1,
"created": 1393239516187,
"currentstatus": "RM01011",
"patternid": -1,
"creator": "admin",
"currentmessage": null,
"forcecheckout": "N",
Chapter 11. Reference

971

"deploymentstatus": null,
"type": "APPLIANCE",
"updated": 1393239552497,
"description": null,
"stage": 1
},
...
]

GET /resources/virtualApplianceInstances/{id} example

{
"currentstatus_text": "Stopped",
"elasticstatus": "",
"name": "My image",
"desiredstatus": "",
"ownerid": 40,
"restartstage": 0,
"environmentprofileid": null,
"elasticmessage": "",
"currentmaintenanceid": null,
"id": 61,
"ipasmastergroupuuid": null,
"deploymentid": null,
"offeringid": -1,
"iptype": "IPv4",
"mode": "",
"priority": 1,
"created": 1393239516187,
"currentstatus": "RM01011",
"patternid": -1,
"creator": "admin",
"currentmessage": null,
"forcecheckout": "N",
"deploymentstatus": null,
"type": "APPLIANCE",
"updated": 1393239552497,
"description": null,
"stage": 1
},

PUT /resources/virtualApplianceInstances/{id} example

Request JSON:
{
"desiredstatus": "RM01011"
}

DELETE /resources/virtualApplianceInstances/{id} example

This REST API deletes a virtual appliance instance. This REST API call do not
accept any parameter.
Example usage:
DELETE /resources/virtualSystems/47

Related tasks:
REST API reference on page 867
The representational state transfer (REST) application programming interface (API)
is provided by IBM Cloud Orchestrator.

972

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Virtual application instances REST APIs

You can use the REST API to manage your virtual application instances.
For many of the APIs, the response includes the status of the virtual application.
For a description of virtual application states, see Deploying virtual application
patterns on page 636.

Retrieve all virtual application instances

GET /resources/virtualApplicationInstances/
Table 163. Retrieve all virtual application instances
Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

complete this action.

403

Access forbidden

500

Unexpected error

Response example:
[
"cloud":"/resources/clouds/1"
"virtual_system_id":"1"
"deployment_name": "test",
"start_time": "2012-04-12T13:38:31.832Z",
"creator": "test",
"create_time": "2012-04-12T13:38:20Z",
"status": "RUNNING",
"access_rights": {
"user1": "F",
"test": "F",
"d-fcca6175-830f-42fa-8c7b-ce144d4e9af5": "R"
},
"app_type": "application",
"app_id": "a-a5685f25-e85b-49c0-b35a-2a50659984c6",
"id": "d-fcca6175-830f-42fa-8c7b-ce144d4e9af5",
"health": "NORMAL",
"role_error": false
}
]

Retrieve virtual application instance status

GET /resources/virtualApplicationInstances/{virtual_application_instance_id}
Table 164. Retrieve virtual application instance status
Example URL

https://localhost/resources/virtualApplicationInstances/d7956c64e-0fac-49f2-b04e-efbc131a4cc4

Response content-type

application/json

Chapter 11. Reference

973

Table 164. Retrieve virtual application instance status (continued)

Response code

200

OK

401

The user is not authorized to

perform this action.

403

This code is returned if the

access is forbidden.

404

The application that is

specified by {appID} is not
found

500

Unexpected error

In addition to the attributes that are used by the "Get a list of virtual application
instances" API, the following attributes are supported:
referenced_services
The shared services this virtual application instance uses.
Roles

A list of middleware for this virtual application instance.

Instances
A list of virtual machines for this virtual application instance. Some key
attributes such as IP and status can be found in each virtual machine
object.
updatable
This attribute contains one object that indicates whether the application is
updatable, it is in the following format: {"can_update":
false,"can_commit_or_revert": false} "can_update" indicates whether it
is updatable. "can_commit_or_revert" indicates whether it can commit or
revert the previous update.
can_resume
This attribute defines whether the virtual application can be resumed from
a maintenance mode, possible values are true or false.
Response example:
{
"referenced_services": [
{
"deployment_id": "d-e8467f98-fb06-47ca-8188-33e6118520c3"
},
{
"deployment_id": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568"
}
],
"deployment_name": "Sample Web Application Only",
"patterntype": "webapp",
"start_time": "2012-04-16T00:16:17.654Z",
"creator": "cbadmin",
"create_time": "2012-04-16T00:16:11Z",
"access_rights": {
"cbadmin": "F",
"d-b4402a23-e64e-4636-b4eb-85b9b01edc28": "R"
},
"status": "LAUNCHING",
"updatable": {
"can_update": false,
"can_commit_or_revert": false
},
"app_type": "application",
"version": "2.0",

974

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"app_id": "a-10eb8a46-a6e7-4344-8b77-b782a3868bae",
"id": "d-b4402a23-e64e-4636-b4eb-85b9b01edc28",
"health": "CRITICAL",
"roles": [
{
"statuses": [
{
"status": "STARTING",
"health": "CRITICAL"
}
],
"name": "Web_Application-was.ElbServicePlaceholder"
},
{
"statuses": [
{
"status": "STARTING",
"health": "CRITICAL"
}
],
"external_uri": [
{
"ENDPOINT": "https://defaultHost:443/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/webapp/"
},
{
"ENDPOINT": "http://defaultHost/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/webapp/"
}
],
"name": "Web_Application-was.WAS"
}
],
"can_resume": false,
"creator_name": "cbadmin",
"instances": [
{
"master": true,
"private_ip": "192.0.2.101",
"role_count": 5,
"reboot.count": 0,
"activation-status": "RUNNING",
"public_hostname": "vm-073-101.mycompany.com",
"start_time": "2012-04-16T00:16:20.624Z",
"hypervisorHostname": "192.0.2.31",
"name": "Web_Application-was.11334535377654",
"health_url": "192.0.2.92",
"last_update": "2012-04-16T00:21:26.794Z",
"vmId": 24,
"status": "RUNNING",
"hypervisorUUId": "30c99382-6e40-e011-9cba-00215e5d6754",
"health_url_src_deployment": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568",
"stopped.by": "",
"volumes": [],
"id": "Web_Application-was.11334535377654",
"uuid": "4221081a-993b-ce5c-3e57-845c393acb10",
"health": "CRITICAL",
"roles": [
{
"status": "STARTING",
"node": "Web_Application-was.11334535377654",
"last_update": "2012-04-16T00:23:18.355Z",
"health_url_src_deployment": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568",
"type": "ElbServicePlaceholder",
"id": "Web_Application-was.11334535377654.ElbServicePlaceholder",
"health_url": "192.0.2.92",
"health": "CRITICAL"
},
{
"status": "STARTING",
"node": "Web_Application-was.11334535377654",
"last_update": "2012-04-16T00:24:06.451Z",
"health_url_src_deployment": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568",
Chapter 11. Reference

975

"external_uri": [
{
"ENDPOINT": "https://defaultHost:443/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/
webapp/"
},
{
"ENDPOINT": "http://defaultHost/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/
webapp/"
}
],
"type": "WAS",
"id": "Web_Application-was.11334535377654.WAS",
"health_url": "192.0.2.92",
"health": "CRITICAL"
}
],
"public_ip": "192.0.2.101"
}
],
"role_error": false
}

Delete a virtual application instance

DELETE /resources/virtualApplicationInstances/{virtual_application_instance_id}
Table 165. Delete a virtual application instance
Example URL

https://localhost/resources/virtualApplicationInstances/d7956c64e-0fac-49f2-b04e-efbc131a4cc4

Response content-type

application/json

Request body

{"success":"true"}

Response code

200

OK
Note: If the deployment
specified by {depl_id} is not
found, a 200 response code
returns, response body:
{"success": "false"}

401

The user is not authorized to

perform this action.

403

Access forbidden

409

Conflict (same action is

already in process)

500

Unexpected error

Success
True indicates that the virtual application instance is found and deleted.
False indicates that the virtual application instance is not found.

Virtual application patterns REST API

You can use the REST API to manage your virtual application patterns.

List all application patterns

GET /resources/virtualApplicationPatterns/
Table 166. List all virtual application patterns

976

Example URL

https://localhost/resources/virtualApplicationPatterns/

Response content-type

application/json

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 166. List all virtual application patterns (continued)

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

500

Unexpected error

Response example:
[
{
"content_type": "application/json",
"last_modifier": "tester",
"create_time": "2011-02-24T05:41:34Z",
"last_modified": "2011-02-24T05:41:34Z",
"access_rights": {
"tester": "F"
},
"content_md5": "661D31C9F14615539E537E9AA5CB02E9",
"app_type": "application",
"app_id": "a-faac12d0-23d7-4f57-b3cb-13ce92d5e07f",
"app_name": "untitled",
"creator": "tester"
},
...
]

Return a specific virtual application patterns

GET /resources/virtualApplicationPatterns/{app_id}
Table 167. Return detailed information about a virtual application patterns
Example URL

https://localhost/resources/irtualApplicationPatterns/a679a68f4-6798-424f-8039-1f682f949f45

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

404

The application that is

specified by {appID} is not
found.

500

Unexpected error

Response example:
{
"last_modifier": "cbadmin",
"content_type": "application/json",
"app_name": "Secured JEE web application",
"creator": "cbadmin",
"create_time": "2011-02-24T05:41:34Z",
"last_modified": "2011-02-24T05:41:34Z",
"access_rights": {
"AllUsers": "R"
},
"content_md5": "60136D4754C7CEE19E827665FE601C33",
"app_type": "application",
Chapter 11. Reference

977

"app_id": "a-679a68f4-6798-424f-8039-1f682f949f45",
"description": "HitCount is a secured Java Platform, Enterprise Edition (Java EE)
web application demonstrating how to increment a counter with WebSphere Application
Server,Tivoli Direcotry Service, and DB2. Access HitCount via http://[IP]:9080/hitcount,
where [IP] is the IP of the deployed WebSphere Application Server virtual machine."
}

Create an application pattern with specific attributes

POST /resources/virtualApplicationPatterns/

Different kinds of attributes can be combined. A unique ID is generated for the

application.
Table 168. Create a virtual application patterns with specific attributes
Example URL

https://localhost/resources/virtualApplicationPatterns/

Request content-type and

body

Content-Type - application/json (appmodel.json file)

Request body example

JSON Application model

Response content-type

application/json

Response header location

https://localhost/resources/virtualApplicationPatterns/a4e21f6e9-2ca7-4a3a-a5cc-00f04f7b7f08

Response code

201

Created

401

The user is not authorized to

perform this action.

403

Access forbidden

412

Invalid parameter supplied,

for example, the JSON file is
invalid.

415

Invalid content type

500

Unexpected error

Content-Type - application/zip file (compressed file that

includes the application model and artifacts files)

Response example:
{
"content_type": "application/json",
"last_modifier": "tester",
"create_time": "2011-02-24T05:41:34Z",
"last_modified": "2011-02-24T05:41:34Z",
"access_rights": {
"tester": "F"
},
"content_md5": "EF7142254CD653D987E9A9E8A48C01D3",
"app_type": "application",
"app_id": "a-4e21f6e9-2ca7-4a3a-a5cc-00f04f7b7f08",
"app_name": "test",
"creator": "tester"
}

Create an application pattern from an existing application or template

(clone)
POST /resources/virtualApplicationPatterns/?source={app_id}&app_name={name}&app_type={app_type}

A unique ID is generated for the application.

v Attribute "source": specify application template or application (required)

978

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Attribute "app_name": specify application name (required)

v Attribute "app_type": specify application type for target application. The values
can be application or template. The default value is application.
Table 169. Create an application pattern from an existing application or template (clone)
Example URL

https://localhost/resources/virtualApplicationPatterns/
?source=a-679a68f4-6798-424f-8039-1f682f949f45
&app_name=testApp
Create an application name testAppfrom application with ID
a-679a68f4-6798-424f-8039-1f682f949f45

Response content-type

application/json

Response header location

https://localhost/resources/virtualApplicationPatterns/afb70796e-1b13-467a-babe-b8b700bd563b

Response code

201

Created

401

The user is not authorized to

perform this action.

403

Access forbidden

412

Invalid parameter supplied,

for example, the application
ID is not found.

415

Invalid content type

500

Unexpected error

Response example:
{
"content_type": "application/json",
"last_modifier": "tester",
"create_time": "2011-02-24T05:41:34Z",
"last_modified": "2011-02-24T05:41:34Z",
"access_rights": {
"AllUsers": "R",
"tester": "F"
},
"content_md5": "7AB9C3524906672BB0E1EA0209FF3803",
"app_type": "application",
"app_id": "a-fb70796e-1b13-467a-babe-b8b700bd563b",
"app_name": "testApp",
"creator": "tester"
}

Deploy a virtual application patterns

There are two options when you deploy a virtual application patterns:
1. Deploy the application with the placement that is determined by the system, if
applicable, or by not using placement if it is not supported by the application.
To deploy the application with this method, use the POST REST API and do not
include the placement_only parameter in the request body, or set it to False.
2. Modify the placement before you deploy the application, and use the modified
placement for the deployment. To use this method, the deployment must be
called in two phases:
v First, generate the placement and topology by including
placement_only:"True" in the request body.

Chapter 11. Reference

979

This parameter tells the system to generate a placement for the deployment,
which is returned in response body. You can modify this placement before
you pass it to the system in the second phase to deploy the pattern.
v Then, deploy the pattern by calling the PUT REST API with the
deployPlacement operation, and pass the modified placement for the
deployment in the request body.
Notes:
v Because placement is handled by the system, you do not have to specify a cloud
group or IP group if an environment profile is specified. If the pattern cannot
use placement, then the cloud group and IP group parameters are required. For
example, if some of the plug-ins in the pattern do not require Foundation 2.1,
the application cannot use placement. In this scenario, the cloud group and IP
group are required. If you do not specify these parameters for a pattern that
cannot use placement, the deployment fails.
v If "placement_only":True is in the request body, but placement is not supported
for the pattern, that parameter is ignored by the system. The pattern is deployed
as if the placement_only was not specified, or was set to False.
Restriction: If your API version is not 5.0.0.0:
v The cloud group and IP group are required parameters.
v Deploying to an environment profile with the cloud management type set to "By
way of external network" is not supported.
Deploy the application or generate the placement if you are using the two-phase
method:
POST /resources/virtualApplicationPatterns/pattern_id/virtualApplicationInstances/
Table 170. Deploy a virtual application pattern
Example URL

http://server/resources/virtualApplicationPatterns/a-123/
virtualApplicationInstances/

Request content-type

application/json

Response headers
content-type

application/json

Response code

201

Created successfully

403

Access forbidden

500

Unexpected error

Request body example for a one-phase deployment that either uses the placement
that is determined by the system, or does not use placement:
{
"deployment_name": "My Virtual Application",
"environment_profile_id": "1",
"ssh_keys":["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCevpm4/EYFrjQ9NkC535Whr3Yswv2xJkx
Gz44/2g5uC6385hWvEycSAyoUQ3pt6/n4BxMHxilLVrT3y9FhyGBfIkJsySvzsiMVe0shh7JWct03uCiiQ5
emoe2eaVOiYz2P5vBe9V8amTC1Is+Uv/SXFF7UuKlV7gP8hBuBNGwnN2/hI6dKtZKH2GDcJbPz9J9dFl2XQ
YoX7XnaJ3eea+UZfIvS21Gi7SF3Ff+/UdPuOumHGhw1S1POGbApFStjOWXU92p6Mz4wON+mRtWzYXGEdlXDA
QisX8yBlZdVZ6+g4HB2cv5TWvYchiAYqG6M1B5tZIr/ZYzEZVTjd4ZCQMwR auto generated key"]
}

Request body for the first phase of a two-phase deployment. Set

"placement_only": true in the request body:

980

IBM Cloud Orchestrator 2.4.0.2: User's Guide

{
"deployment_name": "Two nodes_testname",
"ssh_keys": ["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCoh/DkvoUoio7rMUtoYFGuqFVF+07igSj
xylqhTt/8xM8jjTpBY6qngFBqyjI76ss522Gf8ubqNarqzL6cqLm7ZLI5Fz4FvwQmbux9xK9zicoZ/Hi1QAz
N9mcYt0w7zFKrx79HEye7VZMCeR5PzsATb9oI8F3frx2oS/kFTUNRyul8nTSND3Ae98dcxUUYaXCLkNuSdQs
ZV1rUjxJxQcL0010EiV5TYRtucvznIQ4U5MU2uKP7iLz2/AYojnFafIZi8xD/W/tEj9lCzvKYLiQzsfmsD/2
boziE44d+Af0MjX7DRjZDgF1LJpfnoSFS3PEjeN03jQCqq53LkkWkN5Wb iwd-generated-rsa-key-20140522",
"environment_profile_id": "1",
"placement_only": true
}

Response body example for a one-phase deployment that either uses the placement
that is determined by the system, or does not use placement:
{
"status": "RUNNING",
"deployment_id": "d-7956c64e-0fac-49f2-b04e-efbc131a4cc4",
"deployment_name": "db2",
"app_type": "application",
"app_id": "a-3761fe57-2bda-4f9b-b90c-d2c435d69cb7",
"start_time": "2011-03-25T17:02:57.878Z",
"virtual_system": {
"id":"1"
}
"instances": [
{
"status": "RUNNING",
"master": true,
"last_update": "2011-03-25T17:11:13.750Z",
"private_ip": "1xx.1x2.165.49",
"reboot.count": 0,
"stopped.by": "",
"volumes": [
],
"start_time": "2011-03-25T17:03:51.654Z",
"id": "rack9.xdblade32b04.22889.03473",
"name": "database-db2.11301072577884",
"roles": [
{
"node": "database-db2.11301072577884",
"status": "RUNNING",
"last_update": "2011-03-25T17:11:14.840Z",
"external_uri": "jdbc:db2://1xx.1x2.165.49:50000/mydb:user=appdba;
password=FgxmZv47TM8GwJD62Y1;",
"id": "database-db2.11301072577884.DB2"
}
],
"public_ip": "1x.1xx.165.49"
}
],
"role_error": false
}

Response body example for the first phase of a two-phase deployment. When
"placement_only": true is included in the request body, placement is returned in
the response body:
{
"placement": {
...
},
"deployment_url":
"https://1xx.0.0.1:9443/services/deployments/d-55e08a31-a3f0-419e-b262-3cdba2cf6be2",
"app_type": null,
"topology": [
{
"component_id": "OS Node",
Chapter 11. Reference

981

"name": "OS_Node",
"parameters": [{
"placement": true,
"id": "WAS.PASSWORD",
"label": "ADMIN_USER_PWD_LABEL",
"description":"ADMIN_USER_PWD_DESCRIPTION",
"type":"string",
"displayType":"password"
}],
"scaling": {
"min": 1,
"max": 10,
"init": 2
}
}
],
"app_id": "a-3712cdf6-c919-45e7-b010-b032cc03e35b",
"creator_name": "cbadmin",
"deployment_name": "Two nodes_testname",
"role_error": false,
"deployment_id": "d-55e08a31-a3f0-419e-b262-3cdba2cf6be2",
"creator": "cbadmin"
}

Second phase of a two-phase deployment:

PUT /resources/virtualApplicationInstances/instance_id

You can specify three parameters in the request body:

placement
Required. The modified placement for the deployment.
topology_parameters
Optional. Define the topology parameters that are needed for deployment as a
key value map. The key format is topologyname.parameterid. For example,
WAS.PASSWORD.
addon_parameters
Optional. Define the topology parameters that are needed for deployment as a
key value map.
Table 171. Deploy a virtual application patterns - second phase with modified placement
Example URL

https://localhost/resources/virtualApplications/d-55e08a31a3f0-419e-b262-3cdba2cf6be2

Request content-type

application/json
Specify the updated placement in the request body.

Response code

982

IBM Cloud Orchestrator 2.4.0.2: User's Guide

200

OK

401

The user is not

authorized to perform
this action.

403

Access forbidden

404

The application that is

specified by {appID} is
not found.

412

A specified parameter is
not valid. For example,
the JSON file is not valid.

500

Unexpected error

Request example:
{
"operation": "deployPlacement",
"topology_parameters": {},
"addon_parameters": {},
"placement": { //required
"vm-templates": [{
"locations": [{
"name": "1721665121",
"cloud_groups": [{
"name": "esxset15",
"instances": [{
"new_instances": 1,
"nics": [{
"ip_groups": [{
"name": "172",
"new_instances": 1,
"purpose": "data"
}],
"name": "management",
"purpose": "data"
}]
}]
}],
"new_instances": 1
},
{
"name": "1721665123",
"cloud_groups": [{
"name": "esxset16",
"instances": [{
"new_instances": 1,
"nics": [{
"ip_groups": [{
"name": "172_2",
"purpose": "data",
"new_instances": 1
}],
"name": "management",
"purpose": "data"
}]
}]
}],
"messages": ["CWZKS6401E: 1721665123 is missing image IBM OS Image
for Red Hat Linux Systems:2.1.0.0."],
"new_instances": 1
}],
"environment_profile": "MyTest",
"name": "Web_Application-was",
"new_instances": 2
}],
"version": "5.0.0.0"
}
}

Update a virtual application patterns

PUT /resources/virtualApplicationPatterns/{app_id}
Table 172. Update a virtual application patterns
Example URL

https://localhost/resources/virtualApplicationPatterns/acdaac959-672c-4df7-a648-b333a3843422

Chapter 11. Reference

983

Table 172. Update a virtual application patterns (continued)

Request content-type and
body

Content-Type - application/json (body is the application

model JSON file)
Content-Type - application/zip (body is compressed file,
including the application model and artifacts files)

Request content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

404

The application that is

specified by {appID} is not
found.

412

A specified parameter is not

valid. For example, the JSON
file is not valid.

500

Unexpected error

Response example:
{
"content_type": "application/json",
"last_modifier": "tester",
"create_time": "2011-02-24T05:41:34Z",
"last_modified": "2011-02-24T05:41:34Z",
"access_rights": {
"tester": "F"
},
"content_md5": "5B8F7E6CF56F7CE804788C0086589AFF",
"app_type": "application",
"app_id": "a-fb70796e-1b13-467a-babe-b8b700bd563b",
"name": "App for Testing",
"locked": "false",
"creator": "tester"
}

Delete a specified virtual application patterns

DELETE /resources/virtualApplicationPatterns/{app_id}
Table 173. Delete a specified virtual application patterns

984

Example URL

https://localhost/resources/virtualApplicationPatterns/acdaac959-672c-4df7-a648-b333a3843422

Response content-type

application/json

Response code

200

OK
Note: If an application
specified by {appID} is not
found, the 200 response code
returns, response body:
{"success": "false"})

401

The user is not authorized to

perform this action.

403

Access forbidden

409

Conflict

500

Unexpected error

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Virtual images REST API

You can use the representational state transfer (REST) application programming
interface (API) to manage virtual images.

Available HTTP Methods

Table 174. REST API for VirtualMachines
HTTP
Method

URI Pattern

Data Format

GET

/resources/virtualImages

application/json

GET

GET

/resources/virtualImages/{id}

/resources/clouds/
{cloud_id}/images

application/json

application/json

Success Codes
200

200

200

Error Codes

403
Returns the list
of virtual images
that are visible to
the client.

Returns the
virtual image
associated with
the given ID.

Returns the list

of images of the
selected cloud
group. See the
example for a
sample of the
data returned.

This code is
returned if the
requester does
not have access
to list virtual
images.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403

This code is
returned if the
requester does
not have access
to the requested
virtual image.

404

This code is
returned if the
requested virtual
image is not
defined.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

Chapter 11. Reference

985

Table 174. REST API for VirtualMachines (continued)

HTTP
Method
GET

URI Pattern

Data Format

/resources/clouds/
{cloud_id}/images/
{image_id}

application/json

Success Codes
200

500
Returns the
selected image of
the selected
cloud group. If
you specify a
.ovf suffix the
response is an
OVF XML file.
See the example
for a sample of
the data
returned.

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

200

403
Returns the list
of virtual images
that are visible to
the client.

This code is
returned if the
requester does
not have access
to list virtual
images.

/resources/clouds/
{cloud_id}/images/
{image_id}.ovf

GET

POST

/resources/templates

/resources/templates

application/json

application/json

Error Codes

201

The resources
has been created
successfully.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

A virtual image has the following attributes:

build

Specifies the build number associated with the virtual image. This string
value is supplied by the provider of the virtual image and cannot be
changed.

created
Specifies the creation time of the virtual image, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. The value is numeric
and is automatically generated by the product.
currentmessage
Specifies the message associated with the current status of the virtual
image. This field contains an 8 character string value that is generated by
the product.

986

IBM Cloud Orchestrator 2.4.0.2: User's Guide

currentmessage_text
Specifies the textual representation of currentmessage in the preferred
language of the requester and is automatically generated by the product.
currentstatus
Specifies a string constant representing the current status of the virtual
image. This field contains an 8 character string value that is generated by
the product.
currentstatus_text
Specifies the textual representation of currentstatus in the preferred
language of the requester and is automatically generated by the product.
description
Specifies the description of the virtual image. This string value is supplied
by the provider of the virtual image and cannot be changed.
hypervisortype
Specifies OpenStack as the type of hypervisor on which this virtual image
can run.
id

Specifies the ID of the virtual image. This numeric value is automatically

generated by the product.

linked Specifies 1 (true) if the image is registered from an external hypervisor, 0

(false) if the image has been imported locally. This is a read-only value.
linked_cloudid
Specifies the ID of the cloud group from which the image has been
registered. This is a read-only value and it is set only in the linked
attribute is set to 1 (true).
linked_entityid
Specifies the ID of the image on the external hypervisor. This is a read-only
value and it is set only in the linked attribute is set to 1 (true).
name

Specifies the name of the virtual image. This string value is supplied by
the provider of the virtual image and cannot be changed.

operatingsystemdescription
Specifies a textual description of the operating system contained within the
virtual image. The string value for this optional attribute is supplied by the
provider of the virtual image and cannot be changed.
operatingsystemid
Specifies the numeric ID of the operating system contained within the
virtual image. The ID is one of the values described in the common
information model (CIM) specification and is supplied by the provider of
the virtual image.
operatingsystemid_text
Specifies a textual representation of operatingsystemid.
operatingsystemversion
Specifies the version of the operating system contained within the virtual
image. The string value for this optional attribute is supplied by the
provider of the virtual image and cannot be changed.
owner Specifies the uniform resource identifier (URI) of the user that owns this
virtual image. The URI is relative and should be resolved against the URI
of the virtual image.

Chapter 11. Reference

987

updated
Specifies the time that the virtual image was last updated, represented as
the number of milliseconds since midnight, January 1, 1970 UTC. This
value is numeric and is automatically generated by the product.
version
Specifies the version of the virtual image. This string value is supplied by
the provider of the virtual image and cannot be changed.

GET /resources/virtualImages example

[
{
"currentstatus_text": "Draft",
"name": "My SuSE Small",
"operatingsystemid": 84,
"operatingsystemdescription": "Suse Linux Enterprise 10 (32-bit)",
"hypervisortype": "OpenStack",
"version": "0",
"linked": 1,
"id": 1,
"currentmessage_text": null,
"operatingsystemid_text": "SLES",
"linked_entityid": "1-vm-76",
"created": 1339571308504,
"operatingsystemversion": "10",
"linked_cloudid": 1,
"currentstatus": "RM01027",
"currentmessage": "",
"build": "",
"owner": "/resources/users/1",
"updated": 1339575604458,
"description": "A virtual machine"
},
...
]

GET /resources/virtualImages/{id} example

{
"currentstatus_text": "Draft",
"name": "My SuSE Small",
"operatingsystemid": 84,
"operatingsystemdescription": "Suse Linux Enterprise 10 (32-bit)",
"hypervisortype": "OpenStack",
"version": "0",
"linked": 1,
"id": 1,
"currentmessage_text": null,
"operatingsystemid_text": "SLES",
"linked_entityid": "2496c17c-c303-4dd1-9008-0d16f8161b9c",
"created": 1339571308504,
"operatingsystemversion": "10",
"linked_cloudid": 1,
"currentstatus": "RM01027",
"currentmessage": "",
"build": "",
"owner": "/resources/users/1",
"updated": 1339575604458,
"description": "A virtual machine"
},

GET /resources/clouds/{id}/images example

[
{
"architecture": "x86",

988

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"description": "Microsoft Windows Server 2008 R2 (64-bit)",

"hypervisor": "VMware",
"id": "S1_1-vm-106",
"name": "W2K8_R2-vmx4-CCS-template",
"repository": "S1_1",
"version": "vmx-04",
"linked": "false",
"published": "false"
},
{
"architecture": "x86",
"description": "Red Hat Enterprise Linux 5 (64-bit)",
"hypervisor": "VMware",
"id": "S1_1-vm-43",
"name": "JWeMaestroTemplate",
"repository": "S1_1",
"version": "vmx-04",
"linked": "true",
"templateId": 17,
"published": "true"
},
...
]

GET /resources/clouds/{id}/images/{image_id} example

{
"architecture": "x86",
"description": "Red Hat Enterprise Linux 5 (64-bit)",
"hypervisor": "VMware",
"id": "S1_1-vm-43",
"name": "JWeMaestroTemplate",
"repository": "S1_1",
"version": "vmx-04",
"linked": "true",
"templateId": 17,
"published": "true"
}

GET /resources/templates example

[
{
"currenteditionid": 1,
"advancedoptionsdescription": null,
"name": "My SuSE Small",
"operatingsystemid": 84,
"operatingsystemdescription": "Suse Linux Enterprise 10 (32-bit)",
"ownerid": 1,
"version": "0",
"linked": 1,
"id": 1,
"operatingsystemid_text": "SLES",
"hasadvancedoptions": "F",
"advancedoptionsaccepted": "F",
"linked_entityid": "2496c17c-c303-4dd1-9008-0d16f8161b9c",
"hardware": {
"memory": 192,
"vcpu": 2,
"diskDetails": [
{
"size": "1572864000",
"hardwareid": 1,
"label": "vmdisk1",
"filename": "SLES11_32_Small.vmdk",
"created": 1339571317752,
"updated": 1339571317752,
"id": 1
Chapter 11. Reference

989

}
],
"relatedtype": "TEMPLATES",
"relatedid": 1,
"niccount": 1,
"created": 1339571317669,
"pcpu": 0,
"updated": 1339571317669,
"id": 1
},
"created": 1339571308504,
"licenseaccepted": "T",
"operatingsystemversion": "10",
"linked_cloudid": 1,
"currentstatus": "RM01027",
"published": "T",
"currentmessage": "",
"build": "",
"servicelevel": "0",
"editionstatus": "RM01028",
"parenttemplateeditionid": 0,
"pmtype": "ESX",
"updated": 1339575604458,
"description": "A virtual machine",
"parenttemplateid": 0
},
....
]

POST /resources/templates example

Request JSON:
{
"url": "SampleImageHost/images/SampleImage.ova"
}

where url is the address from which the image can be downloaded or a path to
the locally stored OVA file.

Virtual machines REST API

You can use the representational state transfer (REST) application programming
interface (API) to manage virtual machines.

990

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Available HTTP methods

Table 175. REST API for virtual machines
HTTP
Method
GET

GET

URI Pattern

Data Format

/resources/virtualSystems/
{id}/virtualMachines

application/json

/resources/virtualSystems/
{id}/virtualMachines/{id}

application/json

Success Codes
200

200

Error Codes

Returns the list of 403

virtual system
instances that are
visible to the
client.

Returns the
virtual machine
associated with
the given ID.

This code is
returned if the
requester does
not have access to
list virtual
machines on the
virtual system
instance.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403

This code is
returned if the
requester does
not have access to
the requested
virtual system
instance.

404

This code is
returned if the
requested virtual
machine is not
defined.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

Chapter 11. Reference

991

Table 175. REST API for virtual machines (continued)

HTTP
Method
GET

GET

992

URI Pattern

Data Format

/resources/virtualSystems/
{id}/virtualMachines

application/json

/resources/virtualSystems/
{id}/virtualMachines/{id}

application/json

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Success Codes
200

200

Error Codes

Returns the list of 403

virtual system
instances that are
visible to the
client.

Returns the
virtual machine
associated with
the given ID.

This code is
returned if the
requester does
not have access to
list virtual
machines on the
virtual system
instance.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403

This code is
returned if the
requester does
not have access to
the requested
virtual system
instance.

404

This code is
returned if the
requested virtual
machine is not
defined.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

Table 175. REST API for virtual machines (continued)

HTTP
Method
POST

PUT

URI Pattern

Data Format

/resources/virtualSystems/
{id}/virtualMachines

application/json

/resources/
adoptUnmanagedVM

application/json

Success Codes
201

200

Error Codes

400
The virtual
machine(s) have
been defined in
IBM Cloud
Orchestrator. The
virtual machines
are started when
403
the product is
able to do so. The
response body
contains a list of
URIs for the new
virtual machines.
Relative URIs are
resolved against
the URI used for 500
this request. The
URI of the first
virtual machine is
also included in
the HTTP
Location header
of the response.

This code is
returned if there
are problems
parsing the JSON
data in the
request.

400
The virtual
system instance
was successfully
updated. The
response body is
empty.

This code is
returned if there
are problems
parsing the JSON
data in the
request.

This code is
returned if the
requester does
not have access to
list virtual
machines on the
virtual system
instance.
This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403

This code is
returned if the
requester does
not have
permission to
import the
unmanaged
virtual machine.

404

This code is
returned if the
request references
a resource that is
not defined.

500

This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

A virtual system instance has the following attributes:

Chapter 11. Reference

993

cloud

Specifies the uniform resource identifier (URI) of the cloud group in which
this virtual machine was started. The URI is relative and should be
resolved against the URI of the virtual machine.

cpucount
Specifies the number of virtual CPUs assigned to this virtual machine. This
value is an integer.
created
Specifies the creation time of the virtual machine, represented as the
number of milliseconds since midnight, January 1, 1970 UTC. This value is
numeric and is automatically generated by the product.
currentmessage
Specifies the message associated with the current status of the virtual
machine. This field contains an 8 character string value that is generated
by the product.
currentmessage_text
Specifies the textual representation of currentmessage. This is a string
representation of currentmessage in the preferred language of the requester
and is automatically generated by the product.
currentstatus
Specifies a string constant representing the current status of the virtual
machine. This field contains an 8 character string value that is generated
by the product.
currentstatus_text
Specifies the textual representation of currentstatus. This is a string
representation of currentstatus in the preferred language of the requester
and is automatically generated by the product.
displayname
Specifies the display name used on the hypervisor for this virtual machine.
This field contains a string value with a maximum of 1024 characters.
hypervisor
Specifies the URI of the hypervisor on which this virtual machine is
running. The URI is relative and should be resolved against the URI of the
virtual machine.
hypervisormachineid
Specifies the ID assigned to the virtual machine by the hypervisor. This
field contains a string value with a maximum of 1024 characters.
id

Specifies the ID of the virtual machine. This value is numeric and is

automatically generated by the product.

nics

Specifies a list of the URIs of the IP addresses used by this virtual machine.
URIs are relative and resolved against the URIs of the virtual machine.

memory
Specifies the amount of memory allocated to this virtual machine,
represented in megabytes. This value is an integer.
name

Specifies the display name associated with this virtual machine. This field
contains a string value with a maximum of 1024 characters.

runtimeid
Specifies the runtime ID generated by the hypervisor on which this virtual
machine is running. This field contains a string value with a maximum of
1024 characters.

994

IBM Cloud Orchestrator 2.4.0.2: User's Guide

storageid
Specifies the hypervisor storage ID of the storage on which this virtual
machine resides. This field contains a string value with a maximum of 1024
characters.
updated
Specifies the time the virtual system instance was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This
value is numeric and is automatically generated by the product.

GET /resources/virtualSystems/{id}/virtualMachines example

[
{
"cloud": "/resources/clouds/1",
"cpucount": 1,
"created": 1245376939141,
"currentmessage": "RM07044",
"currentmessage_text": "Virtual machine has been started",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"displayname": "two vm virtual system instance vm-009-238 dmgr",
"hypervisor": "/resources/hypervisors/1",
"hypervisormachineid": "https://virtualwas.rtp.raleigh.ibm.com/
sdk#HostSystem#ha-host",
"id": 8,
"nics": [
{
"ip": "/resources/ipGroups/1/ips/1",
"ip_hostname": "test1",
"ip_address": "192.168.1.100"
}
],
"memory": 2048,
"name": "DMGR 1",
"runtimeid": "https://virtualwas.rtp.raleigh.ibm.com/sdk#VirtualMachine#29424",
"storageid": "https://virtualwas.rtp.raleigh.ibm.com/
sdk#Datastore#49824cfe-4bd840fb-a97b-001a643670e6",
"updated": 1245377403612
},
{
"cloud": "/resources/clouds/1",
"cpucount": 1,
"created": 1245376954282,
"currentmessage": "RM07035",
"currentmessage_text": "Waiting for initialization to complete",
"currentstatus": "RM01005",
"currentstatus_text": "Starting",
"displayname": "two vm virtual system instance vm-009-239 custom",
"hypervisor": "/resources/hypervisors/1",
"hypervisormachineid": "https://virtualwas.rtp.raleigh.ibm.com/
sdk#HostSystem#ha-host",
"id": 9,
"ip": "/resources/ipGroups/1/ips/2",
"memory": 2048,
"name": "Custom Node 3",
"runtimeid": "https://virtualwas.rtp.raleigh.ibm.com/sdk#VirtualMachine#29440",
"storageid": "https://virtualwas.rtp.raleigh.ibm.com/
sdk#Datastore#49824d1c-f0c6ea83-f3e0-001a643670e6",
"updated": 1245377415829
}
]

See the description of GET /resources/virtualSystems/{id}/virtualMachines/{id} for

attribute details.
Chapter 11. Reference

995

GET /resources/virtualSystems/{id}/virtualMachines/{id} example

{
"cloud": "/resources/clouds/1",
"cpucount": 1,
"created": 1245376939141,
"currentstatus_text": "Started",
"currentmessage": "RM07044",
"currentmessage_text": "Virtual machine has been started",
"currentstatus": "RM01006",
"displayname": "two vm virtual system instance vm-009-238 dmgr",
"hypervisor": "/resources/hypervisors/1",
"hypervisormachineid": "https://virtualwas.rtp.raleigh.ibm.com/
sdk#HostSystem#ha-host",
"id": 8,
"ip": "/resources/ipGroups/1/ips/1",
"memory": 2048,
"name": "DMGR 1",
"runtimeid": "https://virtualwas.rtp.raleigh.ibm.com/sdk#VirtualMachine#29424",
"storageid": "https://virtualwas.rtp.raleigh.ibm.com/
sdk#Datastore#49824cfe-4bd840fb-a97b-001a643670e6",
"updated": 1245377675248
}

POST /resources/virtualSystems/{id}/virtualMachines example

Request JSON:
{
"virtualmachine": "/resources/virtualSystems/5/virtualMachines/12",
"desiredcount": 2
}

Response JSON:
[
"/resources/virtualSystems/5/virtualMachines/16",
"/resources/virtualSystems/5/virtualMachines/17"
]

PUT /resources/adoptUnmanagedVM example

Request JSON:
{ "runtimeids": ["runtimeId1,runtimeId2,..."]}

Related tasks:
REST API reference on page 867
The representational state transfer (REST) application programming interface (API)
is provided by IBM Cloud Orchestrator.

Virtual system instances REST API

You can use the REST API to manage virtual system instances.

Deploy a virtual system pattern

POST /resources/virtualSystemPatterns/{pattern_id}/virtualSystemInstances/
Table 176. Deploy a virtual system pattern

996

Example URL

http://server/resources/virtualSystemPatterns/a-123/
virtualSystemInstances/

Request content-type

application/json

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 176. Deploy a virtual system pattern (continued)

Response code

201

OK

403

Access forbidden

500

Unexpected error

Request body:
{
"deployment_name": "simple",
"cloud_group": "1",
"ip_group": "1",
"environment_profile_id": "1",
"model": {
"nodes": [
{
"attributes": {
"ResumableOnError": true,
"SensitiveEnable": false
},
"id": "Debug component"
}
]
},
"selected_oslist": {
"Linux": "*"
},
"ssh_keys": ["ssh-rsa ..."]
}

Retrieve all virtual system instances

GET /resources/virtualSystemInstances/
Table 177. Retrieve all virtual system instances
Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

complete this action.

403

Access forbidden

500

Unexpected error

Response example:
[
"cloud":"/resources/clouds/1"
"virtual_system_id":"1"
"deployment_name": "test",
"start_time": "2012-04-12T13:38:31.832Z",
"creator": "test",
"create_time": "2012-04-12T13:38:20Z",
"status": "RUNNING",
"access_rights": {
"user1": "F",
"test": "F",
"d-fcca6175-830f-42fa-8c7b-ce144d4e9af5": "R"
},
"app_type": "application",
"app_id": "a-a5685f25-e85b-49c0-b35a-2a50659984c6",
"id": "d-fcca6175-830f-42fa-8c7b-ce144d4e9af5",

Chapter 11. Reference

997

"health": "NORMAL",
"role_error": false
}
]

Retrieve virtual system instance status

GET /resources/virtualSystemInstances/{virtual_system_instance_id}
Table 178. Retrieve virtual system instance status
Example URL

https://localhost/resources/virtualSystemInstances/d7956c64e-0fac-49f2-b04e-efbc131a4cc4

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

This code is returned if the

access is forbidden.

404

The system that is specified

by {appID} is not found

500

Unexpected error

Response example:
{
"referenced_services": [
{
"deployment_id": "d-e8467f98-fb06-47ca-8188-33e6118520c3"
},
{
"deployment_id": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568"
}
],
"deployment_name": "Sample Web Application Only",
"patterntype": "webapp",
"start_time": "2012-04-16T00:16:17.654Z",
"creator": "cbadmin",
"create_time": "2012-04-16T00:16:11Z",
"access_rights": {
"cbadmin": "F",
"d-b4402a23-e64e-4636-b4eb-85b9b01edc28": "R"
},
"status": "LAUNCHING",
"updatable": {
"can_update": false,
"can_commit_or_revert": false
},
"app_type": "application",
"version": "2.0",
"app_id": "a-10eb8a46-a6e7-4344-8b77-b782a3868bae",
"id": "d-b4402a23-e64e-4636-b4eb-85b9b01edc28",
"health": "CRITICAL",
"roles": [
{
"statuses": [
{
"status": "STARTING",
"health": "CRITICAL"
}
],
"name": "Web_Application-was.ElbServicePlaceholder"
},
{
"statuses": [

998

IBM Cloud Orchestrator 2.4.0.2: User's Guide

{
"status": "STARTING",
"health": "CRITICAL"
}
],
"external_uri": [
{
"ENDPOINT": "https://defaultHost:443/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/
webapp/"
},
{
"ENDPOINT": "http://defaultHost/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/webapp/"
}
],
"name": "Web_Application-was.WAS"
}
],
"can_resume": false,
"creator_name": "cbadmin",
"instances": [
{
"master": true,
"private_ip": "192.0.2.101",
"role_count": 5,
"reboot.count": 0,
"activation-status": "RUNNING",
"public_hostname": "vm-073-101.mycompany.com",
"start_time": "2012-04-16T00:16:20.624Z",
"hypervisorHostname": "192.0.2.31",
"name": "Web_Application-was.11334535377654",
"health_url": "192.0.2.92",
"last_update": "2012-04-16T00:21:26.794Z",
"vmId": 24,
"status": "RUNNING",
"hypervisorUUId": "30c99382-6e40-e011-9cba-00215e5d6754",
"health_url_src_deployment": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568",
"stopped.by": "",
"volumes": [],
"id": "Web_Application-was.11334535377654",
"uuid": "4221081a-993b-ce5c-3e57-845c393acb10",
"health": "CRITICAL",
"roles": [
{
"status": "STARTING",
"node": "Web_Application-was.11334535377654",
"last_update": "2012-04-16T00:23:18.355Z",
"health_url_src_deployment": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568",
"type": "ElbServicePlaceholder",
"id": "Web_Application-was.11334535377654.ElbServicePlaceholder",
"health_url": "192.0.2.92",
"health": "CRITICAL"
},
{
"status": "STARTING",
"node": "Web_Application-was.11334535377654",
"last_update": "2012-04-16T00:24:06.451Z",
"health_url_src_deployment": "d-47147c5f-5d1e-47ad-8921-1d0d909ad568",
"external_uri": [
{
"ENDPOINT": "https://defaultHost:443/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/
webapp/"
},
{
"ENDPOINT": "http://defaultHost/d-b4402a23-e64e-4636-b4eb-85b9b01edc28/
webapp/"
}
],
"type": "WAS",
"id": "Web_Application-was.11334535377654.WAS",
"health_url": "192.0.2.92",
"health": "CRITICAL"
Chapter 11. Reference

999

}
],
"public_ip": "192.0.2.101"
}
],
"role_error": false }

In addition to the attributes that are used by the "Get a list of virtual system
instances" API, the following attributes are supported:
referenced_services
The shared services this virtual system instance uses.
Roles

A list of middleware for this virtual system instance.

Instances
A list of virtual machines for this virtual system instance. Some key
attributes such as IP and status can be found in each virtual machine
object.
updatable
This attribute contains one object that indicates whether the system is
updatable, it is in the following format: {"can_update":
false,"can_commit_or_revert": false} "can_update" indicates whether it
is updatable. "can_commit_or_revert" indicates whether it can commit or
revert the previous update.
can_resume
This attribute defines whether the virtual system can be resumed from a
maintenance mode, possible values are true or false.

Virtual system instances (classic) REST API

You can use the representational state transfer (REST) application programming
interface (API) to manage virtual system instances (classic).

Available HTTP Methods

Table 179. REST API for VirtualSystems
HTTP
Method

URI Pattern

Data Format

GET

/resources/virtualSystems

application/json

Success Codes
200

Error Codes

403
Returns the list
of virtual system
instances that
are visible to the
client.

500

1000

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This code is
returned if the
requester does
not have access
to list virtual
system
instances.
This code is
returned if IBM
Cloud
Orchestrator
encountered an
internal error
while processing
the request.

Table 179. REST API for VirtualSystems (continued)

HTTP
Method

URI Pattern

Data Format

POST

/resources/virtualSystems

application/json

GET

/resources/virtualSystems/
{id}

application/json

Success Codes
201

200

Error Codes

400
The virtual
system instance
has been created
and is included
in the response
body. The URI
of the new
403
virtual system
instance is
included in the
Location header
of the response.

This code is
returned if there
are problems
parsing the
JSON data in the
request.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403

This code is
returned if the
requester does
not have access
to the requested
virtual system
instance.

404

This code is
returned if the
requested virtual
system instance
is not defined.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

Returns the
virtual system
instance
associated with
the given ID.

This code is
returned if the
requester does
not have
permission to
create virtual
system
instances.

Chapter 11. Reference

1001

Table 179. REST API for VirtualSystems (continued)

HTTP
Method
PUT

DELETE

URI Pattern

Data Format

/resources/virtualSystems/
{id}

application/json

/resources/virtualSystems/
{id}

Success Codes
200

204

Error Codes

400
The virtual
system instance
was successfully
updated. The
response body
contains a JSON
representation of
403
the current state
of the virtual
system.

The virtual
system instance
has been
deleted.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

This code is
returned if the
requester does
not have
permission to
update the
virtual system
instance.

404

This code is
returned if the
request
references a
resource that is
not defined.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

403

This code is
returned if the
requester does
not have
permission to
delete the virtual
system instance.

404

This code is
returned if the
requested virtual
system instance
is not defined.

500

This code is
returned if the
IBM Cloud
Orchestrator
encountered an
internal error
while processing
the request.

The following attributes are required to create a virtual system:

1002

This code is
returned if there
are problems
parsing the
JSON data in the
request.

endtime
Specifies the time the virtual system instance is to be stopped, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This
attribute is optional. If not specified, the virtual system instance will run
until it is manually stopped.
environmentProfile
This attribute specifies the URI of the environment in which to deploy the
new virtual system instance. The environmentProfile attribute must be
specified at this level.
name

Specifies the name for the new virtual system instance.

pattern
Specifies the URI of the pattern to be used for the new virtual system.
virtualimage
Specifies the URI of the virtual image to be used for single image
deployment. 'X-IBM-Workload-Deployer-API-Version' in the header must
be 4.0 and higher to enable this attribute. Either pattern or virtualimage
can be used as attributes.
parts

Specifies a list containing one map per part contained in the pattern.
Because you are using the environmentProfile attribute, then you also use
one of the cloud and ipGroup pairs provided in the environment profile.
The environment profile provides the valid cloud and IP group attributes
for that profile:
cloud

Specifies the URI of the cloud in which to deploy the new virtual
system.

ipGroup
Specifies the URI of the IP Group in which to deploy the new
virtual system.
ipAddress
Specifies the IP address of the virtual machine in the virtual system
instance. This attribute is required when the value of IP addresses
provided by in the environment profile is pattern deployer.
Important: If the environment profile indicates that the pattern
deployer provides the IP address, then you cannot specify an IP
address that is contained within the IP groups that are already
defined in IBM Cloud Orchestrator.
hostname
Specifies the hostname of the virtual machine in the virtual system
instance. This attribute is optional when the value of IP addresses
provided by in the environment profile is pattern deployer.
The following example shows how the ipGroup, ipAddress, and hostname
attributes might be specified:
"nics": [[{
"ipGroup": "/resources/ipGroups/1",
"hostname": "myhostname.mycompany.com",
"ipAddress": "1.1.1.2"
},
{

Chapter 11. Reference

1003

"ipGroup": "/resources/ipGroups/1",
"hostname": "myhostname1.mycompany.com",
"ipAddress": "1.1.1.3"
}]]

The map for each part contains the following attributes:

id

Specifies the ID of the pattern part. This numeric value is

automatically generated by the product.

label

Specifies displayable text used to identify the part.

description
Specifies a textual description of the part.
flavor Specifies the predefined size of the part in terms of CPU and
memory.
properties
Specifies a list containing one map per property defined for the
part.
scripts Specifies a list containing one map per script defined for the part.
The map for each part property contains the following attributes:
description
Specifies a textual description of the property.
key

Specifies a string that uniquely identifies the property within the

part property

label

Specifies displayable text used to identify the property.

pclass Specifies a string value used to identify related properties within a

part. The combination of pclass and key values is unique for every
property contained in a given part.
type

Specifies a string indicating the type of values that can be assigned

to this property. The value will be one of "string", "integer" or
"boolean".

validValues
For properties that are only allowed to have certain values, the
validValues attribute contains a list of the allowable values.
value

Specifies the default value for the property. The type of this value
depends on the property's type.

The map for each script contains the following attributes:

description
Specifies a textual description of the script.
id

Specifies the ID of the pattern script. This numeric value is

automatically generated by the product.

label

Specifies the displayable text used to identify the script.

parameters
Specifies a list containing one map per parameter defined for the
script.
The map for each parameter contains the following attributes:
key

1004

Specifies a string that uniquely identifies the parameter. The script

key is a string with a maximum length of 4098 characters.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

value

The default value for the parameter. All parameter have string
values with a maximum length of 4098 characters.

starttime
Specifies the time the virtual system instance is to be started, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This
attribute is optional. If not specified, the virtual system instance starts as
soon as possible.

GET /resources/virtualSystems example

[
{
"created": 1245041940730,
"currentmessage": null,
"currentmessage_text": null,
"currentstatus": "RM01036",
"currentstatus_text": "Queued",
"desiredstatus": "",
"desiredstatus_text": null,
"id": 6,
"name": "futurevs",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/1",
"updated": 1245041940730
},
{
"created": 1245356439153,
"currentmessage": "RM07045",
"currentmessage_text": "The virtual system instance has been deployed
and is ready to use",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "",
"desiredstatus_text": null,
"id": 9,
"name": "test virtual system instance",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/6",
"updated": 1245357249316
}
]

See the description of GET /resources/virtualsystems/{id} for attribute details.

POST /resources/virtualSystems example

Request JSON:
{
"environmentProfile": "/resources/environmentProfiles/1",
"endtime": 1260000000000,
"name": "sample virtual system instance",
"parts": [{
"description": "Deployment manager",
"label": "Deployment manager",
"id": 1,
"cloudid": "81",
* the ID of the cloud *
"flavor": "m1.tiny",
"ipgroupid": "81",
* the ID of the group *
"ipaddresses":[{
"hostname":"myhostname.mycompany.com",
"ipaddress":"192.168.0.100"
}],
"properties": [{
"description": "Number of virtual CPUs required",
Chapter 11. Reference

1005

"key": "numvcpus",
"label": "Virtual CPUs",
"pclass": "HWAttributes",
"type": "integer",
"validValues": ["1","2","4"],
"value": "1"
},
{
"description": "Memory size required in megabytes",
"key": "memsize",
"label": "Memory size (MB)",
"pclass": "HWAttributes",
"type": "integer",
"value": "3072"
},
{
"description": "This is the cell name of the profile",
"key": "cell_name",
"label": "Cell name",
"pclass": "ConfigWAS",
"type": "string",
"value": "DeployerCell"
},
{
"description": "This is the node name of the profile",
"key": "node_name",
"label": "Node name",
"pclass": "ConfigWAS",
"type": "string",
"value": "DeployerNode"
},
{
"description": "List of feature packs",
"key": "augment_list",
"label": "Feature packs",
"pclass": "ConfigWAS",
"type": "string",
"validValues": ["sca","none"],
"value": "none"
},
{
"description": "This is the root password for the system",
"key": "password",
"label": "Password (root)",
"pclass": "ConfigPWD_ROOT",
"type": "string",
"value": "root-password"
},
{
"description": "This is the password for the system and
WebSphere account (virtuser)",
"key": "password",
"label": "Password (virtuser)",
"pclass": "ConfigPWD_USER",
"type": "string",
"value": "virtuser-password"
}],
"scripts": [{
"description": "Test script",
"id": 1,
"label": "test script",
"parameters": [{
"key": "key1",
"value": "value1"
},
{
"key": "key2",

1006

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"value": "my value2"

}]
}]
},
{
"description": "Custom nodes",
"id": 3,
"label": "Custom nodes",
"cloudid": "1",
* the ID of the cloud *
"flavor": "m1.tiny",
"ipgroupid": "1",
* the ID of the IP group *
"ipaddresses":[{
"hostname":"myhostname.mycompany.com",
"ipaddress":"192.168.0.102"
}],
"properties": [{
"description": "Number of virtual CPUs required",
"key": "numvcpus",
"label": "Virtual CPUs",
"pclass": "HWAttributes",
"type": "integer",
"validValues": ["1","2","4"],
"value": "1"
},
{
"description": "Memory size required in megabytes",
"key": "memsize",
"label": "Memory size (MB)",
"pclass": "HWAttributes",
"type": "integer",
"value": "2048"
},
{
"description": "This is the cell name of the profile",
"key": "cell_name",
"label": "Cell name",
"pclass": "ConfigWAS",
"type": "string",
"value": "DeployerCell"
},
{
"description": "This is the node name of the profile",
"key": "node_name",
"label": "Node name",
"pclass": "ConfigWAS",
"type": "string",
"value": "DeployerNode"
},
{
"description": "This is the root password for the system",
"key": "password",
"label": "Password (root)",
"pclass": "ConfigPWD_ROOT",
"type": "string",
"value": "root-password"
},
{
"description": "This is the password for the system and
WebSphere account (virtuser)",
"key": "password",
"label": "Password (virtuser)",
"pclass": "ConfigPWD_USER",
"type": "string",
"value": "virtuser-password"
}],
"scripts": []

Chapter 11. Reference

1007

}],
"pattern": "/resources/patterns/1",
"starttime": 1250000000000
}

Response JSON:
{
"created": 1245361773378,
"currentmessage": null,
"currentmessage_text": null,
"currentstatus": "RM01036",
"currentstatus_text": "Queued",
"desiredstatus": "",
"desiredstatus_text": null,
"id": 13,
"name": "sample virtual system instance",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/1",
"updated": 1245361773378
}

GET /resources/virtualSystems/{id} example

{
"created": 1245356439153,
"currentmessage": "RM07045",
"currentmessage_text": "The virtual system instance has been deployed
and is ready to use",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "",
"desiredstatus_text": null,
"id": 9,
"name": "test virtual system instance",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/6",
"updated": 1245357249316
}

Note: Key-value pairs that are only used by user interface clients are optional.
A virtual system instance has the following attributes:
created
Specifies the creation time of the virtual system instance, represented as the
number of milliseconds since midnight, January 1, 1970 UTC. This value is
numeric and is automatically generated by the product.
currentmessage
Specifies the message associated with the current status of the virtual
system instance. This is an 8 character string value that is generated by the
product.
currentmessage_text
Specifies the textual representation of currentmessage. This is a string
representation of currentmessage in the preferred language of the requester
and is automatically generated by the product.
currentstatus
Specifies a string constant representing the current status of the virtual
system instance. This is an 8 character string value is automatically
generated by the product.

1008

IBM Cloud Orchestrator 2.4.0.2: User's Guide

currentstatus_text
Specifies the textual representation of currentstatus. This is a string
representation of currentstatus in the preferred language of the requester
and is automatically generated by the product.
desiredstatus
Specifies the desired status of the virtual system instance. Setting this value
causes IBM Cloud Orchestrator to initiate whatever steps are needed to get
the virtual system instance to this state. This value is an 8 character string
value that can only be set to the following values: 'RM01006' (started) or
'RM01011' (stopped), 'RM01020' (snapshot).
desiredstatus_text
Specifies the textual representation of desiredstatus. This is a string
representation of desiredstatus in the preferred language of the requester
and is automatically generated by the product.
id

Specifies the ID of the virtual system instance. This value is numeric and is
automatically generated by the product.

name

Specifies the display name associated with this virtual system instance.
This field contains a string value with a maximum of 1024 characters.

owner Specifies the URI of the user that owns this virtual system instance. The
URI is relative and should be resolved against the URI of the owner.
pattern
Specifies the URI of the pattern used to create this virtual system instance.
The URI is relative and should be resolved against the URI of the pattern.
updated
Specifies the time the virtual system instance was last updated, represented
as the number of milliseconds since midnight, January 1, 1970 UTC. This
value is numeric and is automatically generated by the product.

PUT /resources/virtualSystems/{id} example

Request JSON:
{
"created": 1245356439153,
"currentmessage": "RM07045",
"currentmessage_text": "The virtual system instance has been
deployed and is ready to use",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "RM01011",
"desiredstatus_text": null,
"id": 9,
"name": "test virtual system instance",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/6",
"updated": 1245357249316
}

Response JSON:
{
"created": 1245356439153,
"currentmessage": "RM07028",
"currentmessage_text": "The virtual system instance has
been deployed and is ready to use",
"currentstatus": "RM01010",
"currentstatus_text": "Started",
"desiredstatus": "RM01011",
Chapter 11. Reference

1009

"desiredstatus_text": null,
"id": 9,
"name": "test virtual system instance",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/6",
"updated": 1245357249316
}

DELETE /resources/virtualSystems example

This REST API deletes a virtual system instance and frees the resources it currently
consumes. This REST API call accepts the following single optional query
parameter:
delete-virtual-system-force
A boolean value that indicates the action the product takes if errors are
encountered while deleting the virtual system instance. Valid values are true or
false. If the query parameter is omitted or is assigned the false value, any errors
encountered while deleting the virtual system instance cause the HTTP request
to fail with a 500 error code. If the query parameter is assigned the true value,
errors are ignored and the deleting processing continues.
Example usage:
DELETE /resources/virtualSystems/47?delete-virtual-system-force=true

Related tasks:
REST API reference on page 867
The representational state transfer (REST) application programming interface (API)
is provided by IBM Cloud Orchestrator.

Virtual system patterns REST API

You can use the REST API to manage your virtual system patterns.

Retrieve a list of all virtual system patterns

GET /resources/virtualSystemPatterns
Table 180. Retrieve a list of all virtual system patterns
Example URL

https://localhost/resources/virtualSystemPatterns

Response content-type

application/json

Response code

200

OK

403

Access forbidden

500

Unexpected error

Response example:
[
{
"app_mgmtserver_url": "https://1xx.0.0.1:9443/services/applications/
a-1326e132-5d9e-4830-86d3-1ccb72b29c46",
"last_modifier": "admin",
"app_type": "application",
"app_storehouse_base_url": "https://1xx.0.0.1:9444/storehouse/user/applications/
a-1326e132-5d9e-4830-86d3-1ccb72b29c46/",
"patterntype": "vsys",
"app_name": "BaseImageWithScalingPolicy",
"creator": "admin",
"version": "1.0",
"patternversion": "1.0",
"last_modified": "2014-02-20T20:15:09Z",

1010

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"content_sha2": "c63f76b66b35a718a79b795aaf4fb7b11f600f425cf56c11ef8bd4039d5084837fb0
c8823369b973936e0735be064d8dd581893678328667c4091ac876127715",
"description": "",
"create_time": "2014-02-20T20:15:09Z",
"content_md5": "ce633115cf9ca5981c70ba740b8fd992",
"app_id": "a-1326e132-5d9e-4830-86d3-1ccb72b29c46",
"access_rights": {
"admin": "F",
"_group_:Everyone": "R"
},
"content_type": "application/json"
},
{
"app_mgmtserver_url": "https://1xx.0.0.1:9443/services/applications/
a-14415000-1eb6-4c41-af91-af06d0928296",
"last_modifier": "admin",
"app_type": "application",
"app_storehouse_base_url": "https://1xx.0.0.1:9444/storehouse/user/applications/
a-14415000-1eb6-4c41-af91-af06d0928296/",
"patterntype": "vsys",
"app_name": "was",
"creator": "admin",
"version": "1.0",
"patternversion": "1.0",
"last_modified": "2014-02-20T20:15:22Z",
"content_sha2": "8f5d03d74ea23afda652a367ec85db080690274fb058cf10c1b4ca8d117ccf5c742b4
cd9f8be756d7d3ef05d73af691169dbc1653f84e74ac51d4bf15ffd17c8",
"description": "",
"create_time": "2014-02-20T20:15:22Z",
"content_md5": "85217ef4ce99c65ad0b76697ba5af240",
"app_id": "a-14415000-1eb6-4c41-af91-af06d0928296",
"access_rights": {
"admin": "F",
"_group_:Everyone": "R"
},
"content_type": "application/json"
},
{
"app_mgmtserver_url": "https://1xx.0.0.1:9443/services/applications/
a-7cc55c0b-5656-4e79-93ad-d6935dea71b3",
"last_modifier": "admin",
"app_type": "application",
"app_storehouse_base_url": "https://1xx.0.0.1:9444/storehouse/user/applications/
a-7cc55c0b-5656-4e79-93ad-d6935dea71b3/",
"patterntype": "vsys",
"app_name": "Database",
"creator": "admin",
"version": "1.0",
"patternversion": "1.0",
"last_modified": "2014-02-20T20:15:13Z",
"content_sha2": "398c13c39e49ca8eede91141f4cb1c927a5924652dfe052987c11ca1148f3069e6f
ce89830c53fc989e72f6ff4ffc2f0db527c7bfda3a33ba343e91b24ff9c04",
"description": "",
"create_time": "2014-02-20T20:15:13Z",
"content_md5": "2078bd11bbbdbabc57f855e658e8b31e",
"app_id": "a-7cc55c0b-5656-4e79-93ad-d6935dea71b3",
"access_rights": {
"admin": "F",
"_group_:Everyone": "R"
},
"content_type": "application/json"
},
{
"app_mgmtserver_url": "https://1xx.0.0.1:9443/services/applications/
a-9af3ab60-c60c-4e9e-9f3a-1c31543becde",
"last_modifier": "admin",
"app_storehouse_base_url": "https://1xx.0.0.1:9444/storehouse/user/applications/
a-9af3ab60-c60c-4e9e-9f3a-1c31543becde/",
"app_type": "application",
"patterntype": "vsys",
"app_name": "mytestpattern",
Chapter 11. Reference

1011

"creator": "admin",
"version": "1.0",
"patternversion": "1.0",
"last_modified": "2014-02-19T20:54:28Z",
"content_sha2": "d491baa605f5138e6be87f8efdaa849e5bc3bc0de5522e7977bb6e3be18e964f6fc1
6ef12f613fef419e22fdd081e84fd335ee9",
"description": "",
"create_time": "2014-02-19T20:51:35Z",
"content_md5": "423b79a64893a46817e14cd223fa80aa",
"app_id": "a-9af3ab60-c60c-4e9e-9f3a-1c31543becde",
"access_rights": {
"admin": "F"
},
"locked": "false",
"readonly": false,
"content_type": "application/json"
},
]

Return a specific virtual system pattern

GET /resources/virtualSystemPatterns/pattern ID
Table 181. Return a specific virtual system pattern
Example URL

https://localhost/resources/virtualSystemPatterns/a-1326e1325d9e-4830-86d3-1ccb72b29c46

Response content-type

application/json

Response code

200

OK

403

Access forbidden

500

Unexpected error

Response example:
{
"app_mgmtserver_url": "https://1xx.0.0.1:9443/services/applications/
a-9af3ab60-c60c-4e9e-9f3a-1c31543becde",
"model": {
"nodes": [
{
"id": "OS Node",
"attributes": {
"ConfigPWD_USER.password": "<xor>LzsLChvLTs=",
"HWAttributes.memsize": 2048,
"HWAttributes.numvcpus": 1,
"ConfigPWD_ROOT.password": "<xor>LzsLChvLTs="
},
"type": "image:OS Node:IBM OS Image for Red Hat Linux Systems:2.0.0.4:148"
}
],
"description": "",
"name": "mytestpattern",
"app_type": "application",
"patterntype": "vsys",
"links": [
],
"locked": false,
"readonly": false,
"patternversion": "1.0",
"version": "1.0"
},
"last_modifier": "admin",
"app_type": "application",
"app_storehouse_base_url": "https://1xx.0.0.1:9444/storehouse/user/applications/
a-9af3ab60-c60c-4e9e-9f3a-1c31543becde/",
"layers": [
{

1012

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"id": "layer",
"nodes": [
"OS Node"
]
}
],
"patterntype": "vsys",
"tooling": {
"nodes": [
{
"id": "OS Node",
"location": {
"y": "141px",
"x": "349px"
},
"ismini": false
}
],
"links": [
]
},
"app_name": "mytestpattern",
"version": "1.0",
"patternversion": "1.0",
"creator": "admin",
"content_sha2": "d491baa605f5138e6be87f8efdaa849e5bc3bc0de5522e7977bb6e3be18e964f6
fc16ef12f613fef419e22fdd081e84fd335ee954a4d",
"last_modified": "2014-02-19T20:54:28Z",
"description": "",
"create_time": "2014-02-19T20:51:35Z",
"content_md5": "423b79a64893a46817e14cd223fa80aa",
"access_rights": {
"admin": "F"
},
"app_id": "a-9af3ab60-c60c-4e9e-9f3a-1c31543becde",
"locked": "false",
"content_type": "application/json",
"readonly": false
}

Create a virtual system pattern from an existing virtual system pattern

(clone)
POST /resources/virtualSystemPatterns/?source={app_id}&app_name={name}&app_type={app_type}

A unique ID is generated for the virtual system.

v Attribute "source": specify the ID for the existing virtual system pattern
(required)
v Attribute "app_name": specify the virtual system pattern name (required)
v Attribute "app_type": specify the type for target application. The values can be
application or template. The default value is application.
Table 182. Create a virtual system pattern from an existing virtual system pattern (clone)
Example URL

https://localhost/resources/virtualSystemPatterns/
?source=a-679a68f4-6798-424f-8039-1f682f949f45
&app_name=testSys
Create a virtual system named testSys from application
with ID a-679a68f4-6798-424f-8039-1f682f949f45

Response content-type

application/json

Response header location

https://localhost/resources/virtualSystemPatterns/afb70796e-1b13-467a-babe-b8b700bd563b

Request content-type

application/json

Chapter 11. Reference

1013

Table 182. Create a virtual system pattern from an existing virtual system pattern
(clone) (continued)
Response headers
content-type

application/json

Response body

JSON format of the pattern

Response code

201

Created

403

Access forbidden

404

Not found

500

Unexpected error

Deploy a virtual system pattern

There are two options when you deploy a virtual system pattern:
1. Deploy the virtual system pattern with the placement that is determined by
IBM Cloud Orchestrator, if applicable, or by not using placement if it is not
supported by the virtual system pattern. To deploy the virtual system pattern
with this method, use the POST REST API and do not include the
placement_only parameter in the request body, or set it to False.
2. Modify the placement before you deploy the virtual system pattern, and use
the modified placement for the deployment. To use this method, the
deployment must be called in two phases:
v First, generate the placement and topology by including
placement_only:"True" in the request body.
This parameter tells the system to generate a placement for the deployment,
which is returned in response body. You can modify this placement before
you pass it to the system in the second phase to deploy the virtual system
pattern.
v Then, deploy the virtual system pattern by calling the PUT REST API with the
deployPlacement operation, and pass the modified placement for the
deployment in the request body.
Note:
v Because placement is handled by the system, you do not have to specify a cloud
group or IP group if an environment profile is specified. If the pattern cannot
use placement, then the cloud group and IP group parameters are required. For
example, if some of the plug-ins in the pattern do not require Foundation 2.1,
the application cannot use placement. In this scenario, the cloud group and IP
group are required. If you do not specify these parameters for a pattern that
cannot use placement, the deployment fails.
v If "placement_only":True is in the request body, but placement is not supported
for the pattern, that parameter is ignored by the system. The pattern is deployed
as if the placement_only was not specified, or was set to False.
Restriction: If your API version is not 5.0.0.0:
v The cloud group and IP group are required parameters.
v Deploying to an environment profile with the cloud management type set to "By
way of external network" is not supported.
Deploy the virtual system pattern, or generate the placement if you are using the
two-phase method:
POST /resources/virtualSystemPatterns/pattern ID/virtualSystemInstances/

1014

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Table 183. Deploy a virtual system pattern

Example URL

http://server/resources/virtualSystemPatterns/a-123/
virtualSystemInstances/

Request content-type

application/json

Response headers
content-type

application/json

Response code

201

Created successfully

403

Access forbidden

500

Unexpected error

Request body example for a one-phase deployment that either uses the placement
that is determined by the system, or does not use placement:
{
"deployment_name": "My Virtual System",
"environment_profile_id": "1",
"ssh_keys":["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCevpm4/EYFrjQ9NkC535Whr3Yswv2xJk
xGz44/2g5uC6385hWvEycSAyoUQ3pt6/n4BxMHxilLVrT3y9FhyGBfIkJsySvzsiMVe0sh
h7JWct03uCiiQ5emoe2eaVOiYz2P5vBe9V8amTC1Is+Uv/SXFF7UuKlV7gP8hBuBNGwnN2
/hI6dKtZKH2GDcJbPz9J9dFl2XQYoX7XnaJ3eea+UZfIvS21Gi7SF3Ff+/UdPuOumHGhw1
S1POGbApFStjOWXU92p6Mz4wON+mRtWzYXGEdlXDAQisX8yBlZdVZ6+g4HB2cv5TWvYchi
AYqG6M1B5tZIr/ZYzEZVTjd4ZCQMwR auto generated key"]
}

Request body for the first phase of a two-phase deployment. Set

"placement_only": true in the request body:
{
"deployment_name": "Two nodes_testname",
"ssh_keys": ["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCoh/DkvoUoio7rMUtoYFGuqFVF+07ig
SjxylqhTt/8xM8jjTpBY6qngFBqyjI76ss522Gf8ubqNarqzL6cqLm7ZLI5Fz4FvwQmbux
9xK9zicoZ/Hi1QAzN9mcYt0w7zFKrx79HEye7VZMCeR5PzsATb9oI8F3frx2oS/kFTUNRy
ul8nTSND3Ae98dcxUUYaXCLkNuSdQsZV1rUjxJxQcL0010EiV5TYRtucvznIQ4U5MU2uKP
7iLz2/AYojnFafIZi8xD/W/tEj9lCzvKYLiQzsfmsD/2boziE44d+Af0MjX7DRjZDgF1LJ
pfnoSFS3PEjeN03jQCqq53LkkWkN5Wb iwd-generated-rsa-key-20140522"],
"environment_profile_id": "1",
"placement_only": true
}

Response body example for a one-phase deployment that either uses the placement
that is determined by the system, or does not use placement:
{
"status": "RUNNING",
"deployment_id": "d-7956c64e-0fac-49f2-b04e-efbc131a4cc4",
"deployment_name": "db2",
"app_type": "application",
"app_id": "a-3761fe57-2bda-4f9b-b90c-d2c435d69cb7",
"start_time": "2011-03-25T17:02:57.878Z",
"virtual_system": {
"id":"1"
}
"instances": [
{
"status": "RUNNING",
"master": true,
"last_update": "2011-03-25T17:11:13.750Z",
"private_ip": "1xx.102.165.49",
"reboot.count": 0,
"stopped.by": "",
"volumes": [
],
Chapter 11. Reference

1015

"start_time": "2011-03-25T17:03:51.654Z",
"id": "rack9.xdblade32b04.22889.03473",
"name": "database-db2.11301072577884",
"roles": [
{
"node": "database-db2.11301072577884",
"status": "RUNNING",
"last_update": "2011-03-25T17:11:14.840Z",
"external_uri": "jdbc:db2://1xx.102.165.49:50000/mydb:user=appdba;
password=FgxmZv47TM8GwJD62Y1;",
"id": "database-db2.11301072577884.DB2"
}
],
"public_ip": "1xx.1xx.165.49"
}
],
"role_error": false
}

Response body example for the first phase of a two-phase deployment. When
"placement_only": true is included in the request body, placement is returned in
the response body:
{
"placement": {
...
},
"deployment_url": "https://1xx.0.0.1:9443/services/deployments/
d-55e08a31-a3f0-419e-b262-3cdba2cf6be2",
"app_type": null,
"topology": [
{
"component_id": "OS Node",
"name": "OS_Node",
"parameters": [{
"placement": true,
"id": "WAS.PASSWORD",
"label": "ADMIN_USER_PWD_LABEL",
"description":"ADMIN_USER_PWD_DESCRIPTION",
"type":"string",
"displayType":"password"
}],
"scaling": {
"min": 1,
"max": 10,
"init": 2
}
}
],
"app_id": "a-3712cdf6-c919-45e7-b010-b032cc03e35b",
"creator_name": "cbadmin",
"deployment_name": "Two nodes_testname",
"role_error": false,
"deployment_id": "d-55e08a31-a3f0-419e-b262-3cdba2cf6be2",
"creator": "cbadmin"
}

Second phase of a two-phase deployment:

PUT /resources/virtualSystemPatterns/pattern ID

You can specify three parameters in the request body:

placement
Required. The modified placement for the deployment.

1016

IBM Cloud Orchestrator 2.4.0.2: User's Guide

topology_parameters
Optional. Define the topology parameters that are needed for deployment as a
key value map. The key format is topologyname.parameterid. For example,
WAS.PASSWORD.
addon_parameters
Optional. Define the topology parameters that are needed for deployment as a
key value map.
Table 184. Deploy a virtual system pattern - second phase with modified placement
Example URL

https://localhost/resources/virtualSystemPatterns/acdaac959-672c-4df7-a648-b333a3843422

Request content-type

application/json
Specify the updated placement in the request body.

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

404

The application that is

specified by {appID} is not
found.

412

A specified parameter is not

valid. For example, the JSON
file is not valid.

500

Unexpected error

Request example:
{
"operation": "deployPlacement",
"topology_parameters": {},
"addon_parameters": {},
"placement": {
"vm-templates": [{
"locations": [{
"name": "1721665121",
"cloud_groups": [{
"name": "esxset15",
"instances": [{
"new_instances": 1,
"nics": [{
"ip_groups": [{
"name": "172",
"new_instances": 1,
"purpose": "data"
}],
"name": "management",
"purpose": "data"
}]
}]
}],
"new_instances": 1
},
{
"name": "1721665123",
"cloud_groups": [{
"name": "esxset16",
"instances": [{
"new_instances": 1,
Chapter 11. Reference

1017

"nics": [{
"ip_groups": [{
"name": "172_2",
"purpose": "data",
"new_instances": 1
}],
"name": "management",
"purpose": "data"
}]
}]
}],
"messages": ["CWZKS6401E: 1721665123 is missing image IBM OS Image for
Red Hat Linux Systems:2.1.0.0."],
"new_instances": 1
}],
"environment_profile": "MyTest",
"name": "Web_Application-was",
"new_instances": 2
}],
"version": "5.0.0.0"
}
}

Update a virtual system pattern

PUT /resources/virtualSystemPatterns/pattern ID
Table 185. Update a virtual system pattern
Example URL

https://localhost/resources/virtualSystemPatterns/acdaac959-672c-4df7-a648-b333a3843422

Request content-type

application/json
Specify the updated properties in the request body.

Response code

200

OK

401

The user is not authorized

to perform this action.

403

Access forbidden

404

The application that is

specified by {appID} is
not found.

412

A specified parameter is
not valid. For example,
the JSON file is not valid.

500

Unexpected error

Request example:
{
"content_type": "application/json",
"last_modifier": "tester",
"create_time": "2011-02-24T05:41:34Z",
"last_modified": "2011-02-24T05:41:34Z",
"access_rights": {
"tester": "F"
},
"content_md5": "5B8F7E6CF56F7CE804788C0086589AFF",
"app_type": "application",
"app_id": "a-fb70796e-1b13-467a-babe-b8b700bd563b",

1018

IBM Cloud Orchestrator 2.4.0.2: User's Guide

"name": "App for Testing",

"locked": "false",
"creator": "tester"
}

Delete a specified virtual system pattern

DELETE /resources/virtualSystemPatterns/{vsys_id}
Table 186. Delete a specified virtual system pattern
Example URL

https://localhost/resources/virtualSystemPatterns/acdaac959-672c-4df7-a648-b333a3843422

Response content-type

application/json

Response code

200

OK

401

The user is not authorized to

perform this action.

403

Access forbidden

409

Conflict

500

Unexpected error

Virtual system patterns (classic) REST API

You can use the representational state transfer (REST) application programming
interface (API) to manage virtual system patterns (classic).

Available HTTP Methods

Table 187. REST API for virtual system patterns (classic)
HTTP
Method

URI Pattern

Date Format

GET

/resources/patterns

application/json

Success Codes
200

Returns the list of

patterns that are
visible to the client.
If a 'name=' query
parameter was
supplied, the list of
patterns will contain
only patterns whose
name contains the
specified search
string.

Error Codes
403

This code is returned

if the requester does
not have access to
list patterns.

500

This code is returned

if the IBM Cloud
Orchestrator
encountered an
internal error while
processing the
request.

Chapter 11. Reference

1019

Table 187. REST API for virtual system patterns (classic) (continued)
HTTP
Method
GET

URI Pattern

Date Format

/resources/patterns/
{id}

application/json

Success Codes
200

Returns the pattern

associated with the
given ID.

Error Codes
403

This code is returned

if the requester does
not have access to
the requested
pattern.

404

This code is returned

if the requested
pattern is not
defined.

500

This code is returned

if the IBM Cloud
Orchestrator
encountered an
internal error while
processing the
request.

A pattern has the following attributes:

created
Specifies the creation time of the pattern, represented as the number of
milliseconds since midnight, January 1, 1970 UTC. This value is numeric
and is automatically generated by the product.
currentmessage
Specifies the message associated with the current status of the pattern. This
field is an 8 character string value that is automatically generated by the
product.
currentmessage_text
Specifies the textual representation of currentmessage. This is a string
representation of currentmessage in the preferred language of the requester
and is automatically generated by the product.
currentstatus
Specifies a string constant representing the current status of the pattern.
This field is an 8 character string value that is automatically generated by
the product.
currentstatus_text
Specifies the textual representation of currentstatus. This is a string
representation of currentstatus in the preferred language of the requester
and is automatically generated by the product.
description
Specifies the description of the pattern. This field is a string value with a
maximum of 1024 characters.

1020

id

Specifies the ID of the pattern. This numeric value is automatically

generated by the product.

name

Specifies the name of the pattern. This field is a string value with a
maximum of 1024 characters.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

owner Specifies the uniform resource identifier (URI) of the user that owns this
pattern. The URI is relative and should be resolved against the URI of the
pattern.
parts

Specifies a list containing one map per part contained in the pattern.
The map for each part contains the following attributes:
count

The number of virtual machines that are created from this part
when the pattern is deployed. A value of null indicates that the
part can only be used to construct a single virtual machine. Parts
that can be used to construct multiple virtual machines will have a
positive integer value for this attribute.

description
Specifies a textual description of the part.
id

Specifies the ID of the pattern part. This numeric value is

automatically generated by the product.

label

Specifies displayable text used to identify the part.

properties
Specifies a list containing one map per property defined for the
part.
scripts Specifies a list containing one map per script defined for the part.
virtualimage
Specifies the uniform resource identifier (URI) of the virtual image
associated with the part. The URI is relative and should be
resolved against the URI of the pattern.
The map for each part property contains the following attributes:
description
Specifies a textual description of the property.
key

Specifies a string that uniquely identifies the property within the

part property

label

Specifies displayable text used to identify the property.

pclass Specifies a string value used to identify related properties within a

part. The combination of pclass and key values is unique for every
property contained in a given part.
type

Specifies a string indicating the type of values that may be

assigned to this property. The value will be one of "string",
"integer" or "boolean".

validValues
For properties that are only allowed to have certain values, the
validValues attribute contains a list of the allowable values.
value

Specifies the default value for the property. The type of this value
depends on the property's type.

The map for each script contains the following attributes:

description
Specifies a textual description of the script.
id

Specifies the ID of the pattern script. This numeric value is

automatically generated by the product.

Chapter 11. Reference

1021

label

Specifies the displayable text used to identify the script.

parameters
Specifies a list containing one map per parameter defined for the
script.
The map for each parameter contains the following attributes:
key

Specifies a string that uniquely identifies the parameter. The script

key is a string with a maximum length of 4098 characters.

value

The default value for the parameter. All parameter have string
values with a maximum length of 4098 characters.

updated
Specifies the time the pattern was last updated, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric
and is automatically generated by the product.
virtualsystems
Specifies the list of URIs of the virtual system instances using this pattern.
The URIs are relative should be resolved against the URI of the pattern
that contains them.

GET /resources/patterns example

[
{
"created": 1369136077948,
"version": "1.0.0",
"currentstatus": "RM01027",
"updated": 1369136077948,
"name": "WASPattern",
"id": 2, "description": null,
"currentmessage": null,
"ownerid": 2
},
{
"created": 1369383745603,
"version": "1.0.0",
"currentstatus": "RM01027",
"updated": 1369383745603,
"name": "ConnectedImages",
"id": 6, "description": null,
"currentmessage": null,
"ownerid": 2
},
etc.
]

See the description of GET /resources/patterns/{id} for attribute details.

GET /resources/patterns/{id} example

{
"path": null,
"created": 1369136077975,
"name": "WASPattern",
"currentstatus": "RM01027",
"validationstatus": "RM01001",
"ownerid": 2,
"currentmessage": null,
"validationmessage": "RM06000",
"constraints": [
],
"validation": [

1022

IBM Cloud Orchestrator 2.4.0.2: User's Guide

{
"status": "RM01001",
"message": "RM06000"
}
],
"id": 2,
"updated": 1369145895473,
"counter": 0,
"description": null
}

Note: Key-value pairs that are only used by user interface clients are optional.

GET /resources/patterns/{id}?parts=true example

{
"parts": [
{
"description": "The IBM HTTP server as the Web server",
"memberCount": 1,
"key": "IHSPart",
"partType": "IHS Only Node",
"partVersion": "1.0.0",
"partCaption": "IBM HTTP servers",
"label": "IBM HTTP servers",
"id": 1,
"resid": 6,
"partDescriptiveName": null,
"elasticDisabled": false,
"elastic": true,
"renderColor": "#F2F9E4",
"renderBackgroundImage": "images.zip/bg_f2f9e4.png",
"renderConfigScriptColor": "#E4EFCC",
"renderIcon": "images.zip/http-server-icon.gif",
"renderListIcon": "images.zip/http-server-icon-large.gif",
"requiresAdvancedFunctionEnabled": false,
"supportsIPv6": true,
"hypervisorType": "VMware-ESXi",
"properties": [
{
"description": "Hypervisor for which image is created",
"label": "Hypervisor",
"id": "1",
"key": "Hypervisor",
"value": "VMware-ESXi",
"pclass": "PartInformation",
"instance": "1",
"propDescriptiveName": null,
"locked": "true",
"userConfigurable": "false",
"requiredForDeployment": true,
"propSrc": null,
"propSrcImmediate": null,
"type": "string",
"password": false
},
etc.
],
etc.
}

Related tasks:
REST API reference on page 867
The representational state transfer (REST) application programming interface (API)
is provided by IBM Cloud Orchestrator.

Chapter 11. Reference

1023

1024

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Chapter 12. Troubleshooting

Troubleshooting tools have been collected for ease of use when attempting to
debug an issue.

Before you begin

You must be assigned the admin role to perform these steps.

About this task

The steps to troubleshoot an issue are different for each problem. To help make
relevant information available to you as quickly as possible, the log files and other
tools for troubleshooting problems have been consolidated together for
convenience.

Finding the log files

To troubleshoot the IBM Cloud Orchestrator components, see the following table to
find where the log files are stored.
Table 188. Log files
Component

Log file default path

Node

Self-service user interface

/var/log/scoui.log
/var/log/scoui.trc

Central Server 2

Administration user interface

/var/log/httpd

Central Server 2

OpenStack

/var/log/nova
/var/log/glance
/var/log/cinder
/var/log/heat

Region Server

/var/log/keystone

Central Server 2

/var/log/ceilometer
/var/log/qpid

Central Server 1 and Region

Server

/var/log/neutron

Neutron Server

Collect the logs by running the following

command:

Central Server 1

DB2

su -db2inst1 -s db2support
Installer

/var/log/cloud-deployer

Deployment Server

Deployment Service

/var/log/ds

Deployment Server

HTTP Server

/var/log/httpd

Central Server 2

Hyper-V Compute

c:\Program Files (x86)\IBM\Cloud Manager

with OpenStack\Hyper-V Agent\log\

Hyper-V Server

System Automation Application

Manager

Collect the logs by running the following

command in one line:
/opt/IBM/tsamp/eez/bin/getamdata -all
-outdir /tmp; zip saam_logs.zip
/tmp/*-tsaam_data*

System Automation Application

Manager Server

haproxy

/var/log/haproxy.log

Central Server 2 and Region

Server

Copyright IBM Corp. 2013, 2015

1025

Table 188. Log files (continued)

Component

Log file default path

Node

Tivoli System Automation

/var/ibm/tivoli/common/eez/logs

Central Server 2 and Region

Server

IBM Cloud Orchestrator

Monitoring

/var/log/ico_monitoring

Central Server 1 and Region

Server

Public Cloud Gateway

/var/log/pcg/pcg.log

Central Server 2

Business Process Manager

/opt/ibm/BPM/v8.5/profiles/Node1Profile/
logs

Central Server 2

Business Process Manager

installation

/var/ibm/InstallationManager/logs

Central Server 2

Workload Deployer

/drouter/ramdisk2/mnt/raid-volume/raid0/
logs/error/*

Central Server 3

Workload Deployer inlet

/drouter/ramdisk2/mnt/raid-volume/raid0/
logs/trace/*

Central Server 3

Workload Deployer file server

/drouter/ramdisk2/mnt/raid-volume/raid0/
usr/servers/fileserver/*

Central Server 3

Workload Deployer kernel

services

/drouter/ramdisk2/mnt/raid-volume/raid0/
usr/servers/kernelservices/logs/*

Central Server 3

Workload Deployer storehouse

/drouter/ramdisk2/mnt/raid-volume/raid0/
usr/servers/storehouse/logs/*

Central Server 3

Problem determination with pdcollect tool

The script pdcollect.py is a log collection and log zip utility, which collects logs
from all components in IBM Cloud Orchestrator.
The pdcollect.py script is located in /opt/ibm/orchestrator/pdcollect on the
Deployment Server and Central Server 1.
You can start the script, after an error occurs, to collect as much information as
possible and resolve the error. The script can zip remote files, directories, and logs
from different hosts. Optionally, the script executes defined commands on the
remote system and collects the output of the command execution in a zip file. The
program can also execute batch scripts and collect the output. As a result, one
convenient file is created that contains all logs and output of all hosts and
components that are defined in the environment.
The pdcollect.py script uses two files, which must be in the same directory as the
script itself: Environment.xml and Components.xml.
The Environment.xml file describes default installation host names and the
components. The script uses this file as input to create the work
Environment_work.xml file, which contains the additional dynamic compute nodes
as reported by nova-manage service list, a command in OpenStack that lists
available services.
The file Components.xml contains the relationships between the components and the
actions that can be taken to collect the data and execute the commands on the
specific systems. You can use the example Components.xml to look up the specific
action that can be taken to gather output.

1026

IBM Cloud Orchestrator 2.4.0.2: User's Guide

The dynamic list of compute nodes distinguishes between KVM and VMware
nodes. The components that are assumed on the additional compute nodes need to
have a specific name:
v computeNode: KVM compute host
v vmNode: VMware vCenter host
v esxNode: ESX hypervisor host

Assumptions for using pdcollect tool

v The script is executed as root on the Central Server 1.
v Hosts (remote systems) in Environment.xml are reachable from Central Server 1
through ssh.
v Additional compute nodes are gathered by nova-manage service list.
v Components of additional compute nodes are hardcoded.
v The script is executed as root on the Deployment Server.

Running the pdcollect tool

Run the pdcollect.py script on the Central Server 1 to collect logs from all
components in IBM Cloud Orchestrator.

Before you begin

The pdcollect.py script is located in /opt/ibm/orchestrator/pdcollect on the
Central Server 1.
The script requires the exchange of ssh keys to remote machines before execution.
Run the pdcollect.py script on the Deployment Server to collect Deployment
service logs.

Procedure
On Central Server 1 or the Deployment Server, open the command line and run
the following script as root:
python pdcollect.py [options]

where [options] are:

-h, --help
Shows this help message and exits.
-c Components.xml, --componentfile=Components.xml
Defines the input properties file name. Default name is Components.xml.
-v Environment.xml, --environmentfile=Environment.xml
Defines the environment file name. Default name is Environment.xml.
-o PDCollectlog, --output=PDCollectlog
Defines the output log file name. Default name is PDCollectlog_<date and
time in ISO format>.zip.
-n SYSTEMLIST, --hostips=SYSTEMLIST
Defines the list of the host IP addresses defined in the environment file to
be scanned for log files. Default value is to scan all hosts. Format is:
hostip1,hostip2,hostip3,...

Chapter 12. Troubleshooting

1027

-p COMPONENTLIST, --components=COMPONENTLIST
Lists the components to be scanned for the log files. The COMPONENTLIST
format is component1,component2,component3,...
-s STARTDATE, --start=STARTDATE
Defines the first date of the log sequence. The STARTDATE format is
YYYY-MM-DD.
-e ENDDATE, --end=ENDDATE
Defines the day after the last day of the log sequence. TheENDDATE format is
YYYY-MM-DD .
--version
Shows the pdcollect tool version and exits.
A disclaimer is displayed and logged first to alert you that the data that is
gathered and stored may be confidential and could contain passwords.

Results
As output, a zip file container with the following name is created:
PDCollectlog_<date and time>_<hostname>.zip

Running the pdcollect tool with non-root user

You can run the pdcollect tool with non-root user.

Before you begin

The following commands are all run as root on the server indicated.

Procedure
1. Create a new user SSH for all the Central Servers and Region Servers:
a. On each of the Central Servers and Region Servers:
v Create a new user <yourmechid> and set the password:
useradd -m <yourmechid>
passwd <yourmechaid> #enter at the prompt <yourmechapwd>

v Create the .ssh directory and set file permissions:

su - <yourmechid> -c "mkdir .ssh; chmod 700 .ssh"

b. On Central Server 1:
v Generate the SSH keys for <yourmechid> and cp it to all IBM Cloud
Orchestrator Servers:
su - <yourmechid> -c "ssh-keygen -q -t rsa -N -f ~/.ssh/id_rsa"

v Here $i stands for the IP address of each IBM Cloud Orchestrator server
including Central Server 1:
[root@cs-1] su <yourmechid>
[yourmechid@cs-1] scp ~/.ssh/id_rsa.pub $i:~/.ssh/authorized_keys

Note: Make sure that you accept the server key and the password
required in <yourmechid>.
c. Verify that <yourmechid> on Central Server 1 can SSH to all the IBM Cloud
Orchestrator Servers including Central Server 1 without interruption:
su - <yourmechid> -c "ssh <yourmechid>@$SCO_server_ip"

2. Copy the /opt/ibm/orchestrator/pdcollect and change the directory

permission:

1028

IBM Cloud Orchestrator 2.4.0.2: User's Guide

a. On Central Server 1, copy the directory /opt/ibm/orchestrator/pdcollect

to /home/<yourmechid>:
cp -rf /opt/ibm/orchestrator/pdcollect /home/<yourmechid>

b. Replace Components.xml with Components_nonroot.xml:

cp Components.xml Components.xml.org
cp Components_nonroot.xml Components.xml

c. Replace pdcollect.py with pdcollect_nonroot.py:

cp
cp

pdcollect.py pdcollect.py.org
pdcollect_nonroot.py pdcollect.py

d. Change the owner of /home/<yourmechid>:

chown

-R <yourmechid>:<yourmechidgroup> /home/<yourmechid>/

e. Modify the file pdcollect.py, and replace "yourmechid" with the new user
name:
# User which is used to execute remote commands
SSH_USER = "yourmechid"

3. On each of the IBM Cloud Orchestrator servers, add the user <yourmechid> in
the sudo list:
a. Create a sudoer file named <yourmechid> and place it in /etc/sudoers.d:
The content of the file <yourmechid> is as follows:
Note: Replace <yourmechid> with your new user name.
# sudoers additional file for /etc/sudoers.d/
# IMPORTANT: This file must have no ~ or . in its name and file permissions
# must be set to 440!!!
# this file is for the SAAM mech-ID to call the SCO control scripts
Defaults:<yourmechid> !requiretty
# scripts found in control script directory
# adapt the directoy names to the mech id!
# allow for
<yourmechid> ALL = (root) NOPASSWD:/bin/su - db2inst1 -c db2support, (root) \
NOPASSWD:/bin/find, (root) NOPASSWD:/bin/su, (root) NOPASSWD:/usr/bin/tee, (root) \
NOPASSWD:/bin/netstat, (root) NOPASSWD:/bin/chmod, (root) NOPASSWD:/bin/rm, (root) \
NOPASSWD:/usr/bin/zip, (root) NOPASSWD: /bin/cp

b. Change the sudoer file permission:

chmod 440 <yourmechid>

4. Run pdcollect.py with non-root user:

See Running the pdcollect tool on page 1027, to run pdcollect.py in
/home/<yourmechid>/pdcollect/
Note: While running ./pdcollect.py, it is fine to have an output message like
"scp: XXXXXXXXXXXXXXXX: Permission denied". You can ignore these messages.

Setting logging levels

Set the logging levels of the IBM Cloud Orchestrator components to increase or
decrease the collected troubleshooting information.
When the log data from IBM Cloud Orchestrator components does not provide
enough details needed to determine the root cause of an error, many of the
components have a configurable logging detail setting that you can increase to a
debug level. Note that for some components, this should only be done on a
temporary basis because log file sizes might increase dramatically when these
components are configured to log in debug mode, and the file systems might run
out of space.
Chapter 12. Troubleshooting

1029

v To increase the logging level for the Self-service user interface, edit the
/opt/ibm/ccs/scui/etc/log4j.properties file on Central Server 2, and replace
all occurrences of INFO with TRACE. Restart the user interface with the following
command:
service scui restart

v To increase the logging level for the OpenStack Nova components, edit the
/etc/nova/nova.conf on the Region Servers and add the following line in the
[DEFAULT section:
default_log_levels=amqplib=WARN,sqlalchemy=WARN,boto=WARN,suds=INFO,keystone=INFO,eventlet.wsgi.server=WARN,
smartcloud=DEBUG,nova=DEBUG

v
v

You can change the logging setting for individual Nova components to WARN,
INFO or DEBUG. After changing the logging level, you must restart the Nova
components. For information about starting IBM Cloud Orchestrator services, see
Managing the services on page 223.
To increase the logging level for the OpenStack Glance component edit the
/etc/glance/glance*.conf files on the Region Server and change the Debug
value to True. After changing the logging level, you must restart glance. For
information about starting IBM Cloud Orchestrator services, see Managing the
services on page 223.
To increase the logging level for the OpenStack Keystone component, edit the
/etc/keystone/keystone.conf file on Central Server 2 and change level=WARNING
to level=DEBUG in the [logger_keystone] section. After changing the logging
level, you must restart the Keystone component by running the service
openstack-keystone restart command.
To set the logging level for the Workload Deployer component, see Workload
Deployer log files on page 1031.
The Public Cloud Gateway component uses log4j logging. The
log4j.properties file is located in the /opt/ibm/pcg/etc directory. For more
information about the properties in the log4j.properties file, see the
documentation on the Log4j web site at http://logging.apache.org/log4j.

v To set the logging level for the Business Process Manager component, log on to
the WebSphere Integrated Solutions Console on the Central Server 2 and click
Troubleshooting > Logs and trace to access the Logging and Tracing panel.

Log file rotation

IBM Cloud Orchestrator uses the logrotate mechanism of Linux to manage log file
size and rotation settings. For information about adjusting the settings of the log
files rotation, see the logrotate man page by running the man logrotate
command. Note that you may be required to run the logrotate command using
the -f flag after adjusting settings in the configuration files.
The OpenStack Nova, Cinder, and Glance log rotation settings are defined in the
/etc/logrotate.d/openstack-* files on the Region Server.
The Keystone log rotation settings are defined in the /etc/logrotate.d/openstackkeystone files on Central Server 2.

1030

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Workload Deployer log files

The log files associated with Workload Deployer are stored on the machine where
this component is installed (Central Server 3). The viewable logs can be viewed by
using the user interface or they can be downloaded to your local file system for
review.

Before you begin

You must be assigned the admin role to perform these steps.

About this task

There are 2 log files that can be viewed or downloaded, the error.log file and the
trace.log file. Each log file has a maximum size that it cannot exceed and a file
limit defining the number of versions of that file that can be maintained by
Workload Deployer. Each error.log file can be a maximum of 2 MB in size and up
to five versions of the file are maintained for a total of 10 MB of available data.
Each trace.log file can be a maximum size of 100 MB in size and up to 10
versions of the file are maintained for a total of 1 GB of available data. If a version
of either log file is older than 30 days, then it is automatically removed.
Additionally, the oldest log file is removed if the file limit has been reached and a
new file is created.

Procedure
1. Navigate to PATTERNS > Deployer Administration > Troubleshooting and
expand the Logging section. By expanding the Logging section, you have
access to the available logs using the log viewer and also be able to download
the available logs to your file system for additional review.
2. Click one of the following links to open a new web page and view the log files:
v View current error file to view the error log.
v View current trace file to view trace log.
a. Click Pause to stop new log entries from being appended. This action is
only available if the log viewer is accepting new entries.
b. Click Restart for new entries to be appended. This action is only available if
the log viewer is not accepting new entries because it is paused.
c. Click Clear to clear all the data from the log viewer. This action is available
whether the log viewer is accepting new entries or if it is not accepting new
entries.
3. Click Download log files to save all the available logs to your file system in
.zip format. If you need to view information regarding events that have already
happened, then you must use this link. A window is presented allowing you to
open the compressed file or save it to your file system. The compressed file
includes the current error.log file and the current trace.log file in their
entirety, and the available archived versions of these logs. You can download
all files with a single click.
4. Expand Configure trace levels to view or modify the trace levels A set of
default classes are defined as the trace string to be included in the logs. The
level of trace for these classes can be modified and new classes can be added.
The trace levels provided are based on Java Logging convention and
WebSphere Application Server levels. The complete list of trace levels is listed
later in this section, ordered in ascending order of severity:

Chapter 12. Troubleshooting

1031

v FINE: The trace information is a general trace plus method entry / exit /
return values.
v FINER: The trace information is a detailed trace.
v FINEST: the trace information is an even more detailed trace that includes all
the detail that is needed to debug problems.
v ALL: All events are logged. If you create custom levels, ALL includes your
custom levels and can provide a more detailed trace than FINEST.
v
v
v
v

SEVERE: The task cannot continue, but the component can still function.
WARNING: Potential or impending error.
INFO: General information outlining the overall task progress.
OFF: No events are logged.

Increasing logging will decrease performance. You might need advice from IBM
Customer Support if you want to change the trace levels.
a. Add a trace string. Click Add trace string and enter in a valid trace string.
The trace level for a new trace string is set to INFO by default.
b. Remove a trace string Click the remove icon next to a trace string to remove
that trace string.
c. Modify a trace level. Click the <trace_string> and select a new trace level in
the drop down menu. Click Save to commit the new trace level for the
specified trace string.

Results
After you have completed these steps, you have reviewed all the available log
data.
Related reference:
Example script to configure the trace levels on page 405
This script package sets a trace specification level (example
"com.ibm.ws.ibm.*=info") on all servers in a cell. It can be included on either a
stand-alone pattern part or a Deployment Manager pattern part. Users can specify
the trace specification during deployment.

Known errors and limitations

Check the following sections for information about known errors and limitations in
IBM Cloud Orchestrator.

Product limitations
Review the following list of limitations of IBM Cloud Orchestrator.
v The network adapter of type E1000E is not supported by IBM Cloud
Orchestrator. You cannot deploy images that contain this type of network
adapter.
v For OpenStack, the service users (for example, nova, cinder, glance, heat,
ceilometer) must not be renamed and must be enabled. Also, the service project
must not be renamed and must remain enabled. IBM Cloud Orchestrator has
additional requirements: the admin administrator user and the admin project
(admin tenant) must not be renamed or disabled.
v Virtual System Patterns do not support flavors with a disk size of 0, regardless
of the type of hypervisor used. For Virtual System Pattern deployments, use a
flavor with a disk size that is equal to or greater than the disk size of the image.

1032

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Deploying Windows instances with cloudbase-init and multiple NICs might

fail because Windows operating system does not honor the order of the devices
specified at deployment time.
v For z/VM, if you deploy an image to an ECKD disk that is larger than the
source ECKD disk, or if you use the Administration user interface to resize an
image to a flavor with a larger disk, the additional space is not usable until you
repartition the disk and resize the file system. If you use a flavor with disk size
of 0, which is supported except for Virtual System Pattern deployments, the
virtual machine is created with the same disk size as the source disk, and
therefore avoids the issue. This issue occurs only with ECKD disks.
v For Power and VMware Regions, some of the configuration details of the image
can affect the flavor of a virtual system instance that is deployed from the
image. In the output from the nova show instance_id command, the flavor
might be renamed to a format such as Instance_UUID. You can identify the
correct instance flavor from IBM Cloud Orchestrator by completing the
following steps:
1. Log in to the Self-service user interface.
2. Click PATTERNS > Instances > Virtual System Instances.
3. Select YOUR_INSTANCE_NAME.
4. In the Virtual machines section, expand your virtual machine.
5. In the Hardware and network section, find the Flavor information.
v For VMware Regions, injecting SSH keys into virtual machines is not supported.
When you complete the following OpenStack procedure, the SSH keys are not
injected:
1. Run the ssh-keygen command to generate the SSH keys.
2. Use the nova command or the Administration user interface to add a public
key to OpenStack:
nova keypair-add --pub_key id_rsa.pub keyname

3. Deploy the virtual machine by using the key provided by OpenStack:

nova boot --image imageID --key_name keyname --flavor 2 vmName

4. You can use this key to access the virtual machine:

ssh -i your_private_key user@vm_ip_address

v In a VMware region, after deploying a virtual machine, if you rename the virtual
machine by using vCenter and then you change the flavor by using the
Self-service user interface, the name of the virtual machine is set back to the
original name.
v If an image has been imported to Glance with one of the following procedures:
using the OpenStack command line interface to import disk image to Glance,
as described in Adding images to your OpenStack environment on page
341;
using the single disk OVA image that was imported to the Workload
Deployer component and the image was checked out to the specified region;
the first provisioning of the virtual machine to the VMware hypervisor might:
be slow (for example, might take more than 1 hour) when using single image
deployment of Workload Deployer patterns;
fail due to timeout (by default set to 1 hour) for the virtual machine
registration phase in the OpenStack when deploying by using Workload
Deployer patterns.

Chapter 12. Troubleshooting

1033

The problem does not occur after the first provisioning. If the provisioning fails
due to timeout, you can trigger the provisioning manually to allow the transfer
of the disk image to the target datastore.
v PowerVC limitations:
The Power NPIV feature requires that all of the hosts in a given system pool
have NPIV-capable Fibre Channel adapters.
Instances or other resources cannot be moved from one project to another.
Each PowerVC Region Server has one availability zone only.
Because of an OpenStack limitation, in the Administration user interface,
PowerVC hypervisors are always displayed with an active status. This
limitation might cause that IBM Cloud Orchestrator tries to deploy virtual
machines to an inactive hypervisor.
Workload Deployer does not support pLinux images.
AIX does not support cloud-init; this prevents AIX images deployed via
Single Server Deployment or Heat from being able to leverage password
change or ssh key injection functionality at deploy time.
Shared Storage Pool based images do not support disk resize or extension.
Shared Volume Controller FlashCopy operations can only occur serially per
image; if a copy or extending operation is in progress on a boot volume, you
cannot invoke a new operation to make changes to the volume. You can check
the Shared Volume Controller UI to see whether a FlashCopy is in progress
on the target volume.
The option to specify user SSH keys is not supported if deploying virtual
system classic on Power regions.
v Hyper-V limitations:
Virtual system patterns and virtual system patterns (classic) are not
supported.
Discovery and on-boarding of existing instances into IBM Cloud Orchestrator
is not supported for Hyper-V.
Resizing an instance will temporarily make the instance invisible in Hyper-V
manager. It will be re-added once the resize is finished.
Resizing the disk to a smaller size will result in an error.

Unable to reduce the disk size of VMware and KVM virtual

machines
Changing the flavor does not reduce the disk size of VMware and KVM virtual
machines.
OpenStack provides the API and CLI to resize an existing virtual machine to a
different flavor. You can change the flavor to scale the disk size: up or down. The
original virtual machine is saved for a period of time so that the change can be
rolled back if a problem occurs. Test and explicitly confirm all resizing. When you
confirm a resize, the original virtual machine is removed. If you do not explicitly
confirm or revert the changes, all resizes are automatically confirmed after 24
hours.
Some hypervisors do not support scaling down the disk size:
VMware
You cannot resize the virtual machine from a large disk size to a smaller
disk size. The resize operation fails with an error message.
KVM

1034

No error message is displayed, but the disk size is not reduced.

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Disk resize of a template with multiple disks

Increasing the flavor resizes only the boot disk during deployment. An attached
additional disk will not be changed.
Limitations:
v The resize functionality takes into consideration only the boot disk, it does not
take into consideration the additional disks/volumes.
v When deploying on a VMware region a template that has multiple disks, the
flavor checks done at deployment time take into consideration the overall space
needed by all disks and not only the size of the boot disk.
v When resizing on a VMware region an instance that has been deployed from a
template with multiple disks, the last disk of the template is resized instead of
the boot disk.

Hypervisor errors
You can receive error messages for hypervisors defined to IBM Cloud Orchestrator
under certain circumstances.

Minus (-) free disk is displayed in OpenStack for command nova

hypervisor-show
Problem
After the deployment of IBM Cloud Orchestrator, use the following
commands to get the nova information:
[root@vmware-region1 images]# nova hypervisor-show 1
+----+----------------------+
| ID | Hypervisor hostname |
+----+----------------------+
| 1 |
computenodeB
|
+----+----------------------+
[root@vmware-region1 images]# nova hypervisor-show 1
+---------------------------+------------------------------------------------------------------------+
| Property
| Value
|
+---------------------------+------------------------------------------------------------------------+
| cpu_info_model | ["Intel(R) Xeon(R) CPU X5560 @ 2.80GHz", "Intel(R) Xeon(R) CPU X5570 @ 2.93GHz"] |
| cpu_info_topology_cores | 16
|
| cpu_info_topology_threads | 32
|
| cpu_info_vendor
| ["IBM", "IBM"]
|
| current_workload
| 0
|
| disk_available_least
| |
| free_disk_gb
| 25
|
| free_ram_mb
| -43934
|
| host_ip
| 192.0.2.60
|
| hypervisor_hostname
| domain-c7(HA-Cluster1)
|
| hypervisor_type
| VMware vCenter Server
|
| hypervisor_version
| 5001000
|
| id
| 1
|
| local_gb
| 1919
|
| local_gb_used
| 2171
|
| memory_mb
| 89698
|
| memory_mb_used
| 133632
|
| running_vms
| 18
|
| service_host
| vmware-region1
|
| service_id
| 6
|
| vcpus
| 32
|
| vcpus_used
| 58
|
+---------------------------+------------------------------------------------------------------------+

Solution
disk_available_least for hypervisor can be a negative number to indicate
the over commitment of hypervisor disk space.

Chapter 12. Troubleshooting

1035

The qcow2 disk format is used for the virtual machine in the KVM
hypervisor, the whole size of disk will not be allocated from beginning to
save the disk space, disk_available_least comes from the following
equation:
disk_available_least = free_disk_gb - disk_overcommit_size
disk_overcommit_size =
virtual size of disks of all instance instance - used disk size of all instances

When the hypervisor instances overcommitted more disk space than free
disk space, disk_available_least is a negative number.

Minus (-) free_ram_mb or current_workload is displayed in

OpenStack for command nova hypervisor-show
[root@vmware-region1 images]# nova hypervisor-show 1
+---------------------------+------------------------------------------------------------------------+
| Property
| Value
|
+---------------------------+------------------------------------------------------------------------+
| cpu_info_model | ["Intel(R) Xeon(R) CPU X5560 @ 2.80GHz", "Intel(R) Xeon(R) CPU X5570 @ 2.93GHz"] |
| cpu_info_topology_cores | 16
|
| cpu_info_topology_threads | 32
|
| cpu_info_vendor
| ["IBM", "IBM"]
|
| current_workload
| 0
|
| disk_available_least
| |
| free_disk_gb
| 25
|
| free_ram_mb
| -43934
|
| host_ip
| 192.0.2.60
|
| hypervisor_hostname
| domain-c7(HA-Cluster1)
|
| hypervisor_type
| VMware vCenter Server
|
| hypervisor_version
| 5001000
|
| id
| 1
|
| local_gb
| 1919
|
| local_gb_used
| 2171
|
| memory_mb
| 89698
|
| memory_mb_used
| 133632
|
| running_vms
| 18
|
| service_host
| vmware-region1
|
| service_id
| 6
|
| vcpus
| 32
|
| vcpus_used
| 58
|
+---------------------------+------------------------------------------------------------------------+

The free_ram_mb for hypervisor can be a negative number to indicate the over
commitment of hypervisor memory. The default memory overcommit rate is 1.5,
that means you can use memory overall memory_mb * 1.5 memories. The default
cpu overcommit rate is 16, that means you can use memory overall vcpus * 16
vcpus.
To configure the overcommit rate, you must modify the following attribute in
nova.conf and restart the openstack-nova-scheduler and the openstack-novacompute services.
Note: This configuration is effective for KVM, PowerVC, and VMware regions.
# virtual CPU to Physical CPU allocation ratio (default: 16.0)
cpu_allocation_ratio=16.0
# virtual ram to physical ram allocation ratio (default: 1.5)
ram_allocation_ratio=1.5

1036

IBM Cloud Orchestrator 2.4.0.2: User's Guide

OpenStack fails to resize Kernel-based virtual machines

Problem
If you try to resize a Kernel-based virtual machine that uses the
config_drive parameter, the status of the virtual machine changes to
ERROR.
Solution
Do not resize a virtual machine that uses the config_drive parameter. You
can use the following command to check it:
nova show instance_id/instance_name

Image errors
There are some known errors that might occur when managing images in IBM
Cloud Orchestrator.

Error deploying a Windows virtual image

When deploying a Windows virtual image in a pattern, the following Microsoft
error is displayed in the hypervisor console:
Windows could not parse or process the unattend answer file for pass [specialize].
The settings specified in the answer file cannot be applied.
The error was detected while processing settings for component [Microsoft-Windows-Shell-Setup].

Causes
This error might happen if you specified the wrong product key for the Windows
operating system of the image you are deploying.
Resolving the problem
Configure the virtual image part in the pattern by specifying the right product key
for the Windows operating system and deploy the virtual image again.

Limitation: When deploying a Windows image on VMware, you

must match the number of NICs with the number of networks
and IP addresses used for deployment
This limitation occurs when you deploy Windows images using VMware. For
example, a Windows image with two defined NICs must be deployed using two or
more networks. If you try to deploy it using only one network, the deployment
will fail.

Cannot reach the virtual machine deployed in nova

In /etc/sysconfig/network comment or remove GATEWAYDEV=<some-if>.
This directive might cause the deployed virtual machine routing table to be set
incorrectly and therefore the virtual machine might result unreachable.

Disabling VNC in nova.conf can cause some images to not

display completely
If you disabled the VNC in nova.conf (vnc_enable=false) then some images might
not deploy completely. You can see a message like boot from harddisk for the
instances in the console log. The reason is that OpenStack does not prepare the
Chapter 12. Troubleshooting

1037

graphic device for the instance if the VNC is disabled. Therefore, if the image is
depending on the graphic during the boot time, it will hang and will not boot up.

Cannot complete the deployment of an image

Deleting a flavor and creating a new one with the same ID, the old flavor is
always used in Workload Deployer even when the user selects to use the new
flavor.
This is a known OpenStack issue. The deleted flavor is always returned if the new
one has the same ID. The workaround is to create a new flavor with a different ID.

Cannot import a virtual image

When importing a virtual image, the following error message is displayed:
CWZCO1030E: An image with name <image_name> is already defined in the database.

but an image with the same name is not displayed in the image list.
Causes
The problem occurs if you are importing a virtual image with the catalogeditor
role and another user already imported an image with the same name.
Resolving the problem
Ask a user with the admin role to perform one of the following actions:
v Granting the access to the existing virtual image to the project to which your
user belongs.
v Registering the new virtual image with a different name and then granting the
access to the virtual image to the project to which your user belongs.

Instance errors
There are some known errors that might occur when managing instances in IBM
Cloud Orchestrator.

OpenStack reports an rpc error in the log when deleting an

instance
The log might show:
TRACE nova.openstack.common.rpc.amqp
File "/usr/lib/python2.6/site-packages/nova/compute/manager.py", line 923,
in _delete_instance nova.openstack.common.rpc.amqp
instance["uuid"])
TRACE nova.openstack.common.rpc.amqp
File "/usr/lib/python2.6/site-packages/nova/consoleauth/rpcapi.py", line 68,
in delete_tokens_for_instance
TRACE nova.openstack.common.rpc.amqp
instance_uuid=instance_uuid))
TRACE nova.openstack.common.rpc.amqp
File "/usr/lib/python2.6/site-packages/nova/openstack/common/rpc/proxy.py", line 80,
in call

Solution:
Install openstack-nova-console*.rpm that can be found in your IBM Cloud
Orchestrator package and then run:
/etc/init.d/openstack-nova-consoleauth restart

1038

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Failed to deploy instance, it shows "No valid host was found"

When you deploy instance , it shows ERROR immediately and use nova show
<instance name>, it shows No Valid host was found.
This is because the nova scheduler is not able to find a hypervisor to provision the
virtual machine , this usually happens when :
1. Not clean unused virtual machine for a long time.
2. Provisioning more virtual machines than the cloud capacity.
3. Disable or remove hypervisor from cloud like remove ESXi host from VMware
vCenter, KVM compute is down/offline.
To understand if the cloud is out of capacity , you can use nova hypervisor show
<hypervisor id> to check CPU/memory/disk that is used by the virtual machines
on each hypervisor.
To debug the problem, you can modify the /etc/nova/nova.conf and change the
debug and verbose to true as following:
debug=true
verbose=true

Restart the openstack-nova-scheduler and after a failure , you should be able to

see following messages in /var/log/nova/scheduler.log:
2014-09-16 10:15:37.672 28695 DEBUG nova.scheduler.filters.ram_filter
[req-ef6b203c-e0fa-4ba0-8f9f-b2d71ca3deb9 e417380bc10b48c1b5fb4296d6fa470d
26e0b2a9767848f88cd62d7580682bf0] (cil017110014, domain-c19(cluster110))
ram:-42019 disk:267230208 io_ops:0 instances:24 does not have 2048 MB usable ram,
it only has -27444.5 MB usable ram. host_passes
/usr/lib/python2.6/site-packages/nova/scheduler/filters/ram_filter.py:60
2014-09-16 10:15:37.673 28695 INFO nova.filters
[req-ef6b203c-e0fa-4ba0-8f9f-b2d71ca3deb9 e417380bc10b48c1b5fb4296d6fa470d
26e0b2a9767848f88cd62d7580682bf0] Filter RamFilter returned 0 hosts
2014-09-16 10:15:37.673 28695 WARNING nova.scheduler.driver
[req-ef6b203c-e0fa-4ba0-8f9f-b2d71ca3deb9 e417380bc10b48c1b5fb4296d6fa470d
26e0b2a9767848f88cd62d7580682bf0] [instance: a4086e77-389e-4eb8-9431-de5eb6da07f0]
Setting instance to ERROR state.

Which indicate the RAM is not enough to host one more virtual machine with 2
GB required.

Deployment errors
There are some known errors that might occur when deploying virtual system
patterns and images in IBM Cloud Orchestrator.

Setting the host name when deploying a Windows system

When deploying a Windows system, you must specify a computername.
The computername value is set as the virtual instance host name. If you want to set
the host name of the virtual instance to something different than the string
specified in computername, you can create a script package and add it to the image
in the virtual system pattern.
The content of the script can be similar to the following sample:

Chapter 12. Troubleshooting

1039

nslookup $IPADDR | findstr Name > %TEMP%\oldhostname

set /p str=<%TEMP%\oldhostname
echo."%str%"
set str=%str: =%
echo."%str%"
set str=%str:Name:=%
echo."%str%"
wmic COMPUTERSYSTEM where "Name=COMPNAME" CALL Rename str,
Password, User
reboot

where
v IPADDR is the value passed from IBM Cloud Orchestrator as
${partname.ipaddr}

v COMPNAME is the value you specify in computername.

v Password is the administrator password.
v User is typically Administrator.
Attention: This script example reboots the image.
This limitation impacts the usage of property variables in virtual system patterns
when dealing with Windows parts, because ${part-name_.hostname} is not
resolved correctly. The workaround in this case is to use the ${part-name_.ipaddr}
parameter instead. For more information about the property variables, see
Properties variable syntax.

Unable to deploy a virtual system pattern with a non-admin user

You might be unable to deploy a virtual system pattern or virtual application
pattern with a non-admin user.
Symptom
The deployment fails with the following in the Workload Deployer log:
[2013-07-14 23:36:49:222 EDT] 00013567 RegisterTask I
com.ibm.ccs.openstack.shim.task.RegisterTask register About to create server:
SCO-192-0-2-10-18-Web_Application-was.11373859355504
[2013-07-14 23:36:49:580 EDT] 00013567 RegisterTask E
com.ibm.ccs.openstack.shim.task.RegisterTask register Error creating OpenStack instance
com.ibm.openstack.api.exceptions.OpenStackItemNotFoundException: The resource could not be found.
at com.ibm.openstack.api.OpenStackException.<init>(OpenStackException.java:12)
at com.ibm.openstack.api.OpenStackBadResponseException.<init>(OpenStackBadResponseException.java:12)
at sun.reflect.GeneratedConstructorAccessor16.newInstance(Unknown Source)

Solution
To solve this problem, perform the following steps:
1. All networks created in OpenStack must be created with --project
<project id> parameter specified. If a network is to be shared across
multiple users, the easiest way is to define a Public project and include
all users in that project.
Because in a multi-tenancy scenario each project must have its own
network created and assigned, make sure that your project has one
network attached. For example, project003 has network 192.0.2.0/24
attached, then the member of project003 can deploy successfully.
Verify that the specified network ID belongs to the project that you
currently use, by using the following commands:
[root@SVT-CIL-NEW ~]# keystone tenant-list
+----------------------------------+------------+---------+
|
id
|
name
| enabled |

1040

IBM Cloud Orchestrator 2.4.0.2: User's Guide

+----------------------------------+------------+---------+
| 1f9f8b62052046ee97763f4eb88288e3 | service
|
true |
| 3c8b192caab1499aa4aeb2dcf4280a12 |
admin
|
true |
| c7ea7db95d2241c383f2f5995b31fa19 | project003 |
true |
+----------------------------------+------------+---------+
[root@SVT-CIL-NEW ~]# nova-manage network list
id IPv4
IPv6 start address DNS1
1
192.0.2.0/24
None 192.0.2.10
192.0.2.2
project
c7ea7db95d2241c383f2f5995b31fa19

DNS2
192.0.2.2

VlanID
4090

...
...

2. If you want to associate an existing network to a project, run the

following command:
nova-manage network modify <x.x.x.x/yy> <project_id>

where
v <x.x.x.x/yy> is the network to be modified.
v <project_ID> is the ID of the project to be associated.
For example:
nova-manage network modify 192.0.2.0/24 c7ea7db95d2241c383f2f5995b31fa19

Error displayed when deploying a virtual system pattern

You might see the message "Missing cloud or ip group configuration on parts.
Please make a selection before deployment.".
Symptoms:
When deploying a pattern, for example, a virtual system pattern with a
Linux image (RHEL-mini), an error message might be returned indicating
that a cloud or group IP is missing: "Missing cloud or ip group
configuration on parts. Please make a selection before deployment."
Causes:
This occurs because the cloud or IP group was not specified and, in some
cases, the Flavor field might also be empty.
Solution:
After selecting Deploy, select Configure virtual parts and enter the
required details.

Unable to deploy WebSphere Application Server OVA image

When you try to deploy the WebSphere Application Server OVA image on
PowerVM or VMware, the operation might hang.

Solution
To resolve the problem, set the disk size of the image flavor to 0. The flavor then
uses the default size of the image to be deployed.
Alternatively, set the disk size of the flavor to a value that is equal to, or greater
than, the size of the image to be deployed. To identify the correct value, use the
nova image-show image_ID | grep disk command, as shown in the following
example:
nova image-show 4223c31a-4fcf-1747-b3e3-478d44510201 | grep disk
| metadata customization.disksize.hard disk 1
| {"category": "Storage Settings", "name": "DiskSize.Hard disk 1",
"classification": {"id": "STORAGE", "label": "Storage"},
"rules":
Chapter 12. Troubleshooting

1041

[{"id": "increment", "value": "1"},

{"id": "incrementType", "value": "LINEAR"},
{"id": "max", "value": "23538"},
{"id": "min", "value": "12288"}],
"required": false,
"value": 12288,
"type": "LONG",
"description": "Disk Size of Hard disk 1 (MB)"}

Note: Line breaks and indents have been inserted in the command output, to
make the example easier to read.
In this example, the disk size required to create an instance of this image is 12288.

Deployment of the virtual system pattern fails due to the name of

the virtual machine
When deploying a virtual system pattern to an environment profile that has
custom definition of the virtual machine name property using the ${hostname}
variable, the deployment fails.

Symptoms
The deployment history ends with the following message:
Virtual machine could not be registered

date/time

In addition, when browsing the Virtual Machines section of the failed instance, you
see that the name of the virtual machines containing just the first octet of the IP
address instead of the host name, for example d_192 when the IP address of the
machine is like 192.0.*.*.

Causes
The DNS entry is missing in the forward lookup zone for the IP address which has
been assigned to the virtual machine. You can find the exact address in the
hypervisor tools (vCenter or OpenStack).

Resolving the problem

There are the following ways to solve this issue:
v Update the DNS configuration, so that it correctly resolves the host name for the
given IP address. This is the preferred way.
v Change the virtual machine name format property from the environment profile
definition to not use ${hostname} or remove it completely.

Script execution does not report failing condition

When deploying a virtual machine on Power with an additional user created
through add-on, the potential failures are not shown as a failed status of the script.

Symptoms
The user is not properly created on the newly provisioned Power virtual machine
even if the add user script has run and is marked as successfully completed on the
virtual machine details.

Causes
This is an issue with the add-on script being used, which is not properly handling
the error condition and always completing with success.

1042

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Resolving the problem

You must perform additional manual steps to verify that user has been properly
created:
v Open the Scripts section within the particular virtual machine in the pattern
instance.
v Locate the user add-on script.
v Download the remote_std_err.log log and verify if it contains any error
messages.

No valid host was found

Exceeded the maximum scheduling attempts of three for instance <instance_id>.

Cause
The actual deployment of a virtual machine failed since an error occurred while
placing the virtual machine in the cloud. This error message hides the actual root
cause of the problem.

Resolving the problem

To identify the root cause of the problem, the administrator must check the
compute.log of the Compute Node in the corresponding region and also check the
scheduler.log and api.log files. The reason of the problem could be caused by a
bandwidth of issues, like datastore is full, disk is out of space, not enough IP
addresses available, and so forth.

nova command errors and limitations

Check errors and limitations when using the nova command.

nova command limitation

Nova client does not work with users outside of the default domain defined in
OpenStack, so only users in default domain can run the nova command.

The nova-manage command is not able to validate the project ID

This happens if you update quotas or networks for a project that does not exist,
and so the nova-manage command is not able to use the keystone API to verify if
the project exists.
The OpenStack community decided to deprecate nova-manage in future releases for
everything except the db-sync command, and move all functionality out of it into
APIs. For details, you can see a blueprint at https://blueprints.launchpad.net/
nova/+spec/apis-for-nova-manage.
Due to these limitations and the deprecation of the nova-manage command, this
problem will not be fixed. In the current IBM Cloud Orchestrator release, the
nova-manage command can still be used to manage nova resources.

Chapter 12. Troubleshooting

1043

Security limitations
Check the known security limitations that might expose your IBM Cloud
Orchestrator environment to risks.

Toolkit parameters are saved in the log file

The SCOrchestrator toolkit saves in the log file all parameters passed by other
toolkits used by runbooks. If these parameters contain security sensitive
information, they are visible in the <path to BPM profile>/log/bpm4sco1/
SystemOut.log file
Refer to Troubleshooting Business Process Manager on page 1061 for detailed
information on this security limitation.

Unable to change the flavor of VMware virtual machines

Attempts to change the flavor of VMware virtual machines by using OpenStack
fail with an error.
If:
v You try to change the flavor of VMware virtual machines by using OpenStack,
the OpenStack server object is in an error state
v The virtual machine itself is not affected.
You must verify the following settings for /etc/nova/nova.conf:
v If there is only one compute node, set allow_resize_to_same_host to true.
v Set multi_host to false.
You must also make sure that the virtual machine uses an SCSI disk.

Error message displayed when trying to start a virtual system

The resource could not be found message might be displayed when a user from a
newly created project tries to start a virtual system.
An example of this situation is when you run the following command to run a
virtual machine from OpenStack:
nova boot --image rhelova --flavor m1.large --nic net-id=e325a701-ab07-4fb9-a7df-621e0eb31c9b test1vm2

The following message is displayed:

ERROR: The resource could not be found. (HTTP 404) (Request-ID:
req-4d801615-5fb3-49fe-8830-860de3f3f7db)
The reason for the error is that the user cannot access the network that is defined
in the environment profile for the virtual system. This problem occurs when a user
who is associated with one project (for example, Project A) tries to access a
network that is associated with another project (for example, Project B).
The problem can be caused because of the following issues:
v The network was manually associated with Project B, as described in
Associating a Nova network to a project on page 91.
v The network was automatically associated with Project B when an admin user
from Project B booted a virtual machine from OpenStack without specifying the
network:
Using the API: Omitted the networks parameter

1044

IBM Cloud Orchestrator 2.4.0.2: User's Guide

 Using the CLI: Omitted the --nic parameter

If the network is not specified in the boot command, and if the project of the
current user is not associated with any network, OpenStack associates the
network with the project of the current user: in our example, Project B.
If a network is associated with a project, that network cannot be accessed by users
from any other project.
To resolve this problem, you must associate the network with the appropriate
project to ensure that the users assigned to that project can access that network.
You can associate a network with only one project. If you want users from multiple
projects to access the same network, you must disassociate all projects from the
network, which sets the project_id value for the network to None.
For details about how to associate a network with a project, and how to
disassociate all projects from a network, see Associating a Nova network to a
project on page 91.

Unable to list keystone endpoints on the Region Server

You are unable to list keystone endpoints on the Region Server.
This limitation is due to OpenStack and the keystone version 3 support not being
complete. To support keystone version 3, the keystone client must use
OS_SERVICE_TOKEN and OS_SERVICE_ENDPOINT .
Symptoms:
The keystone endpoint URL is empty when running the keystone endpoint-list
command on the Region Server with the /root/openrc sourced:
. openrc
keystone endpoint-list
+----------------------------------+-------------+-----------+-------------+---------|
id
|
region
| publicurl | internalurl | adminurl
+----------------------------------+-------------+-----------+-------------+---------| 019e393701f5436480d6ec9552cd0642 | RegionOne |
|
|
| 08f15c7f3b764af4ad7209404cdd6c05 | RegionOne |
|
|
| 1c76d4c3cd7e4eb683f92202c1fbceee | RegionOne |
|
|
| 40846cc21c7f4477b9d123dd06b5b190 | RegionOne |
|
|
| 8203260f686047bb811435078177ad10 | RegionOne |
|
|
| 895206c5c7144fcb8c00ca657b8e2bb5 | RegionOne |
|
|
| 97781db45f6e41d69768220025f37523 | RegionOne |
|
|
| a691b7ae28834a96a31c39764fe93af2 | RegionOne |
|
|
| a752e8a14f914bf5b868faf813aa1c49 | RegionOne |
|
|
| b41db8b713ba41c1b45f4172f7231e4e | RegionOne |
|
|
| b52a97b7c3af42e1bc61a67c5065cd01 | RegionOne |
|
|
| c0d4ae1fec4a442c84f5f3f14a5191a6 | RegionOne |
|
|
| d0ad615e0a0745de85ad6f8d137998ce | RegionOne |
|
|
| d9591717925c42c99bcba0dbc27d264c | RegionOne |
|
|
| df6f33f4e0144189a413e5385db6f255 | RegionOne |
|
|
+----------------------------------+-------------+-----------+-------------+---------+----------------------------------+
|
service_id
|
+----------------------------------+
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| e6c343c911c844c9b6fb492166e3945a |
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| 2b84a9bc5c6f4338aba4d638072d5624 |
Chapter 12. Troubleshooting

1045

| e6c343c911c844c9b6fb492166e3945a |
| e6c343c911c844c9b6fb492166e3945a |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 18877e517fdd4643921ceb3b354c928b |
| 18877e517fdd4643921ceb3b354c928b |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| 18877e517fdd4643921ceb3b354c928b |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 2b84a9bc5c6f4338aba4d638072d5624 |
| be9192ecbe7c4306beebf8efaf2b49b9 |
+----------------------------------+

Solution:
1. Copy /root/keystonerc from central-server-2. Change the OS_REGION_NAME
variable to the corresponding region name.
2. Source the copied keystonerc:
source keystonerc

3. Rerun the keystone endpoint-list command.

Unable to log in by using an LDAP user

You are unable to log in to IBM Cloud Orchestrator with an LDAP user after
configuring Microsoft Active Directory.
Symptoms:
As an LDAP user, if you try to run any command in OpenStack, for
example, nova list, you get the following error: ERROR: Invalid
OpenStack Nova credentials.
Causes:
When searching from the domain level, Active Directory returns referrals
(search continuations) for some objects, to indicate to the client where to
look for these objects. Client-chasing of referrals is a broken concept, since
LDAP v3 does not specify which credentials to use when chasing the
referral. Windows clients are supposed to use their Windows credentials,
but this does not work in general when chasing referrals received from and
pointing to arbitrary LDAP servers. As a result, the default libldap
automatically chases the referrals internally with an anonymous access,
which fails with Active Directory.
Solution:
To resolve this issue, you must switch off this behavior. Edit the
/usr/lib/python2.6/site-packages/keystone/common/ldap/core.py file to
add the following line under the ldap.initialize line:
self.conn.set_option(ldap.OPT_REFERRALS,0)

Unable to add disk to SLES instance

SLES hotplug of virtual disk is not fully supported.

Symptoms
The Default add disk add-on failed or the device requested in the Default raw
disk add-on is not present in the fdisk -l output.

Resolving the problem

Manually request a reboot from the virtual machine or stop and restart it from the
user interface, and click Execute Now in the virtual machine script packages
section.

1046

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Errors of 32-bit library files libstdc++.so.6 and

/lib/libpam.so* were not found in db2prereqcheck.log
The following errors are not critical and can be ignored.
Validating "32 bit version of "libstdc++.so.6" " ...
Found the 64 bit "/usr/lib64/libstdc++.so.6" in the following directory "/usr/lib64".
DBT3514W The db2prereqcheck utility failed to find the following 32-bit library file:
"libstdc++.so.6".
Validating "/lib/libpam.so*" ...
DBT3514W The db2prereqcheck utility failed to find the following 32-bit library file:
"/lib/libpam.so*".
WARNING : Requirement not matched.
Requirement not matched for DB2 database "Server" . Version: "10.5.0.2".
Summary of prerequisites that are not met on the current system:
DBT3514W The db2prereqcheck utility failed to find the following 32-bit library file:
"/lib/libpam.so*".

Unable to reach one of the addresses if multiple NICs of a

Linux virtual machine are deployed
The router of the second IP address is not set in the virtual machine
automatically.

Problem
The problem occurs because in Linux there is only one default gateway, which
means that even if the network packet can reach the second NIC, the response
packet still uses the default gateway. At that point, the response packet is not able
to reach the sender.

Solution
The solution is to manually add another routing table by performing the following
steps:
1. Determine which is the default gateway and which NIC needs to add an
additional route table. Run the command:
ip addr show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 16436 qdisc noqueue state UNKNOWN
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
2: eth0
<BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1454 qdisc pfifo_fast state UP qlen 1000
link/ether fa:16:3e:cd:c3:17 brd ff:ff:ff:ff:ff:ff
inet 192.0.1.145/24 brd 192.0.1.255 scope global eth0
inet6 fe80::f816:3eff:fecd:c317/64 scope link
valid_lft forever preferred_lft forever
eth1:
<BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1454 qdisc pfifo_fast state UP qlen 1000
link/ether fa:16:3e:f8:a4:f2 brd ff:ff:ff:ff:ff:ff
inet 192.0.2.4/24 brd 192.0.2.255 scope global eth1
inet6 fe80::f816:3eff:fef8:a4f2/64 scope link
valid_lft forever preferred_lft forever

Now, the virtual machine has two NICs: eth0 has 192.0.1.145, eth1 has
192.0.2.4.
Check the route table:

Chapter 12. Troubleshooting

1047

route -n
Kernel IP routing table
169.254.169.254
192.0.1.0
192.0.2.0
169.254.0.0
169.254.0.0
192.0.2.1

Destination Gateway
192.0.2.3
0.0.0.0
0.0.0.0
0.0.0.0
0.0.0.0
0.0.0.0

Genmask
Flags Metric Ref
255.255.255.255 UGH 0
0
255.255.255.0
U
0
0
255.255.255.0
U
0
0
255.255.0.0
U
1002
0
255.255.0.0
U
1003
0
UG
0
0

Use
0
0
0
0
0
0

Iface
eth1
eth0
eth1
eth0
eth1
eth1

so the NIC eth1 has a default gateway that can be reached from the outside,
while eth0 does not have a gateway so it cannot be reached from other
networks.
2. You must add another route table for eth0. Use following command (eth0 is
the name of the route table or you can provide your own meaningful name):
echo "1 eth0" >> /etc/iproute2/rt_tables

3. Configure the routing rules for table eth0:

ip
ip
ip
ip

route add 192.0.1.0/24 dev eth0 src 192.0.1.145 table eth0

route add default via 192.0.1.1 dev eth0 table eth0
rule add from 192.0.1.145/32 table eth0
rule add to 192.0.1.145/32 table eth0

Unable to access the Administration user interface

You are unable to access the Administration user interface.

Problem
A user cannot access the Administration user interface after successful installation.
This is not a common error and occurs only if the node runs out of space.

Solution
Check if there is enough space on Central Server 2 in and if the user has created
any softlink to manage the space on the partition. Then, make sure that the
targeted folder has write permissions. The installer requires write permission on
directories, such as /tmp, /var/tmp, /usr/tmp, /var/www. If you have mounted
these directories on the target directory, make sure that they have write permission
by group, for example 777 permission on /tmp, /var/tmp.

User name and password for vCenter are incorrect

At the beginning of the installation of a VMware Region, you are required to input
information for the vCenter. If you enter an incorrect user name or password for
vCenter, the VMware Region does not connect to the vCenter.

Problem Determination
If you get nothing when running nova list and nova hypervisor-list, check the
following files and services:
1. /var/log/nova/compute.log:
2014-08-05 23:40:38.779 10710 ERROR suds.client [-] <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:ns0="urn:vim25" xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<ns1:Body>
<ns0:Login>
<ns0:_this type="SessionManager">SessionManager</ns0:_this>
<ns0:userName>root</ns0:userName>
<ns0:password>object00!</ns0:password>
</ns0:Login>

1048

IBM Cloud Orchestrator 2.4.0.2: User's Guide

</ns1:Body>
</SOAP-ENV:Envelope>
2014-08-05 23:40:38.782 10710 CRITICAL nova.virt.vmwareapi.driver [-] Unable to connect
to server at 172.19.4.9, sleeping for 60 seconds
2014-08-05 23:40:38.782 10710 TRACE nova.virt.vmwareapi.driver Traceback (most recent call
last):
2014-08-05 23:40:38.782 10710 TRACE nova.virt.vmwareapi.driver
File "/usr/lib/python2.6/site-packages/nova/virt/vmwareapi/driver.py", line 1067,
in _create_session 2014-08-05 23:40:38.782 10710 TRACE nova.virt.vmwareapi.driver
password=self._host_password)
2014-08-05 23:40:38.782 10710 TRACE nova.virt.vmwareapi.driver
File "/usr/lib/python2.6/site-packages/nova/virt/vmwareapi/vim.py", line 203,
in vim_request_handler 2014-08-05 23:40:38.782 10710 TRACE nova.virt.vmwareapi.driver details)
2014-08-05 23:40:38.782 10710 TRACE nova.virt.vmwareapi.driver
VimFaultException: Cannot complete login due to an incorrect user name or password.

2. /etc/init.d/openstack-nova-compute status:
[root@sco24-a28-node2 init.d]# ./openstack-nova-compute status
openstack-nova-compute (pid 10710) is running...

Note: The service openstack-nova-compute is supposed to be running even if

the user name or password is wrong. This service cannot connect to the
vCenter but by itself is OK.

Validate user name and password

Provide the correct user name and password. You can ask for it from your vCenter
administrator. Then you can validate the user name and password in the following
ways:
1. Use vsphere to log into the vCenter with user name and password.
2. Use webclient to log into the vCenter with user name and password:
https://<vcenter-ip>:9443/vsphere-client/.
If the user name and password are correct, the login is successful.

Configure the /etc/nova/nova.conf

Use the following commands to configure /etc/nova/nova.conf:
openstack-config --set /etc/nova/nova.conf vmware host_username vCenter_username
openstack-config --set /etc/nova/nova.conf vmware host_password vCenter_password

Note: If you want the vCenter_password encrypted, you can use

openstack-obfuscate vCenter_password first.

Restart openstack-nova-compute
You must restart openstack-nova-compute:
service openstack-nova-compute restart

Chapter 12. Troubleshooting

1049

Hypervisors remain in maintenance mode

After Workload Deployer deployment, the hypervisors remain in maintenance
mode. To start them again, perform the following procedure.
Solution
1. Log on to the Self-service user interface as an administrator.
2. Go to PATTERNS > Deployer Configuration > Cloud Groups.
3. For each cloud group, expand the cloud hardware section and check
the status of the related hypervisors.
4. For each hypervisor in maintenance mode, click the hypervisor name to
open the Hypervisor window.
5. Expand the Networks and Storage devices sections and ensure that
there is at least one network and storage device marked as in use.
6. Start the hypervisor.

Unable to list all the existing resources

The number of items returned in a single response from resources, like virtual
machines or volumes, is limited to 1000.

Causes:
The API or user interface only lists 1000 resources. This is an intentional limit as a
larger result sets require greater cost to derive and manage.

Solution:
If it is desired to see a larger result sets, increase the maximum number of
instances returned in a single response by setting the osapi_max_limit property in
the /etc/nova/nova.conf file in the Compute Nodes of the related region. This will
impact several interfaces, including the Nova list interface, the Horizon
administrative user interface, and the IBM Cloud Orchestrator user interface. To
manage all instances in a region, the recommended setting would be the maximum
number of instances for the region and a growth buffer. For example, if the region
can contain 2000 instances, and a 10% growth buffer is desired, a limit of 2200
should be used.

Cannot configure a nova compute service to connect to more

than four vCenter clusters
According to the length of metadata column (255) in the instance table, you cannot
configure the nova compute service to connect to more than four vCenter clusters,
otherwise the VMware discovery tool might fail to discover the instances from the
vCenter.
The following error is displayed in the /var/log/nova/discovery.log file:
2014-09-05 20:10:23.599 4400 ERROR vmware.nova.driver.compute.manager [-]
Insert a new VMware instance failed.

To solve the problem, follow the procedures described in Configuring

vmware-discovery for multiple vCenters on page 116 and Connecting to multiple
clusters on page 104.

1050

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Failed to start a virtual system instance on a KVM Region

A virtual system instance failed to start on a KVM Region.

Problem
When you use the Self-service user interface to start an instance on a KVM
Region by clicking PATTERNS > Instances > Virtual System Instances, the
instance hangs in Launching status. However, in the nova list command output,
the image has ACTIVE status.

Causes
The KVM Compute Node hardware clock is configured as LOCAL instead of UTC.

Solution
Complete the following steps on each KVM Compute Node in the region:
1. Log on to the KVM Compute Node as a root user.
2. Edit the /etc/adjtime file to ensure that the hardware clock is configured as
UTC, as shown in the following example:
619.737272 1411131873 0.000000
1411131873
UTC

3. Make sure that the current system clock is synchronized with the time server.
For example, you can use one of the following commands to synchronize the
system clock:
v sntp -sS ntp_host
v ntpd -gq; ntp-wait
v rdate -s ntp_host
v ntpdate ntp_host
4. Save the current system clock to hardware by running the following command:
hwclock --systohc

Failed to use the SSH key file to deploy IBM Cloud

Orchestrator
This topic describes how there might be a failure to use SSH key file to deploy
IBM Cloud Orchestrator.

Problem:
When you use the key file to create a node, the node shows as UNAVAILABLE state.
If you check the deployment server log file you will find the following error:
[Errno 13] Permission denied: u/home/marty/.ssh/id_rsa execute
/usr/lib/python2.6/site-packages/ds/engine/deploy/node_create/_080_check_resources.py:59

Solution:
This is because the deployment server will use the Heat user to access the key file
provided. Make sure that the Heat user has access to the key file.

Chapter 12. Troubleshooting

1051

Lost metadata after updating the aggregate availability zone

The existing metadata in your aggregate recorder will lose after you run the
command nova aggregate-update in the availability zone.

Workaround
As a workaround, you must specify the availability zone when you create this
aggregate, or must reset the metadata after updating the aggregate.

Cannot log in to Administration user interface if Public Cloud

Gateway-only region installed
You are unable to log in to the Administration user interface when a Public Cloud
Gateway-only region is installed.

Problem
The default landing page for the Administration user interface is the hypervisor
page. This page is not accessible for a Public Cloud Gateway region.

Solution
Change the default landing page to the domain page. To change the landing page
on Central-Server2, complete the following steps:
1. Edit the Administration user interface configuration: /etc/openstackdashboard/local_settings.
2. Update the following line: "HORIZON_CONFIG[user_home] = lambda user:
/admin/hypervisors if user.is_superuser else /project" to
"HORIZON_CONFIG[user_home] = lambda user: /admin/domains if
user.is_superuser else /project".
3. Restart the Administration user interface: service httpd restart.

Unable to deploy VMware virtual system pattern in

multi-language environment
Refer to this topic if you are unable to deploy a VMware virtual system pattern in
a multi-language environment with a java.lang. Exception and ascii decode error.

Symptom
When you deploy a VMware virtual system pattern in a multi-language
environment you get the following error message: TRACE nova.api.openstack
UnicodeDecoderError: "ascii" codec cant decode byte 0xe7 in position 28:
ordinal not in range (128).

Problem Description
Environment:
Platform & Locale: zh_CN.utf8
vCenter: S.Chinese Windows 2008 R2

After the installation of IBM Cloud Orchestrator, the following tasks are
performed:

1052

IBM Cloud Orchestrator 2.4.0.2: User's Guide

1. Import an ova image, for example rhel-mini-ext3-vmdk.ova, into VMware

through the Deploy OVF Template in VMware client. After completing this,
convert the ova image into a template.
2. Login in the IBM Cloud Orchestrator server and register the image in Workload
Deployer.
3. Click PATTERNS > Pattern Design > Virtual System Patterns and create a
VMware virtual system pattern.
4. Deploy the pattern with the image rhel-mini-ext3-vmdk.
Result:
Failure to deploy VMware virtual system pattern. When you check the error.log
in Central Server 3, you find the following error:
[2013-04-25 22:10:58:474 EDT] 00001069 RegisterTask E com.ibm.ccs.openstack.shim.task.RegisterTask
register Error creating OpenStack instance
java.lang.Exception: Error getting image with id 4223c473-ad8a-a0cd-06dc-639fdfcbc23b from OpenStack
at com.ibm.ccs.openstack.shim.task.RegisterTask.register(RegisterTask.java:361)
at com.ibm.ccs.openstack.shim.task.RegisterTask.registerVirtualSystem(RegisterTask.java:262)
at com.ibm.ccs.openstack.shim.task.RegisterTask.register(RegisterTask.java:127)
at com.ibm.ccs.openstack.shim.task.RegisterTask.registerVirtualSystemType(RegisterTask.java:175)
at com.ibm.ccs.openstack.shim.task.RegisterTask.register(RegisterTask.java:125)
at com.ibm.ccs.openstack.shim.task.RegisterTask.doCall(RegisterTask.java:112)
at com.ibm.ccs.openstack.shim.task.RegisterTask.doCall(RegisterTask.java:68)
at com.ibm.ccs.openstack.shim.task.BaseTask.call(BaseTask.java:87)
at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:314)
at java.util.concurrent.FutureTask.run(FutureTask.java:149)
at com.ibm.vespa.util.task.VSPLocalTaskHandle.run(VSPLocalTaskHandle.java:75)
at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:897)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:919)
at java.lang.Thread.run(Thread.java:736)
Caused by: com.ibm.openstack.api.OpenStackBadResponseException: The server has either erred or is
incapable of performing the requested operation.
at sun.reflect.GeneratedConstructorAccessor16.newInstance(Unknown Source)
at sun.reflect.DelegatingConstructorAccessorImpl.newInstance
(DelegatingConstructorAccessorImpl.java:39)
at java.lang.reflect.Constructor.newInstance(Constructor.java:527)
at com.ibm.openstack.api.internal.impl.DefaultBadResponseHandlerImpl.instantiateException
(DefaultBadResponseHandlerImpl.java:74)
at com.ibm.openstack.api.internal.impl.DefaultBadResponseHandlerImpl.createException
(DefaultBadResponseHandlerImpl.java:66)
at com.ibm.openstack.api.internal.impl.OpenStackURIHandlerImpl.createInputStream
(OpenStackURIHandlerImpl.java:181)
at org.eclipse.emf.ecore.resource.impl.ExtensibleURIConverterImpl.createInputStream
(ExtensibleURIConverterImpl.java:354)
at org.eclipse.emf.ecore.resource.impl.ResourceImpl.load(ResourceImpl.java:1256)
at com.ibm.openstack.api.service.impl.AbstractOpenStackService.invoke
(AbstractOpenStackService.java:190)
at com.ibm.openstack.api.service.impl.AbstractOpenStackService.invokeGet
(AbstractOpenStackService.java:239)

Using the command glance image-show XXX, you can see that many properties are
in Simple Chinese, which is consistent with vCenter.

Solution
This issue happens due to support issues for a multi-language environment. There
are two different default string encoding settings in Python:
* Python 2.x: ASCII
* Python 3.x: UTF-8

This problem happens because ASCII is set as the default encoder in the
environment. If you want to change Python 2.x to use UTF-8 by default, you must
add the following three lines into the service daemon script:
Chapter 12. Troubleshooting

1053

import sys
reload(sys)
sys.setdefaultencoding("UTF-8")

In an IBM Cloud Orchestrator environment, if you want to enable nova-api,

nova-scheduler and nova-compute daemon to use utf-8 encoding by default, you
must insert the above three lines into the following files:
/usr/bin/nova-api: line #31
/usr/bin/nova-scheduler: line #28
/usr/bin/nova-scheduler: line #27
import eventlet
eventlet.patcher.monkey_patch()
import os
import sys
<=== add the above content under this line.
reload(sys)
*
sys.setdefaultencoding("UTF-8")
*
import traceback

Note:
v The above line number might be different, but the basic principle for the change
is to add those three lines following the line import sys closely.
v If you decide to change the default encoding, you must be aware that
unpredictable errors might happen, as the default encoding form affects the
translation between Python and the outside world, and also all internal
conversions between 8-bit strings and Unicode.

Users cannot log in to the user interface

Users are unable to log in to the user interface, using their correct user names and
passwords.

Cause
Check that the openstack-keystone component is online on Central Server 2 by
running the following command on Central Server 1:
/opt/ibm/orchestrator/scorchestrator/SCOrchestrator.py \
--status --components=openstack-keystone

Solution
If the Keystone process is not online, restart it by running the following command
on Central Server 2:
/opt/ibm/orchestrator/scorchestrator/SCOrchestrator.py
\--start --components=openstack-keystone

Check that the process is online by running the following command:

/opt/ibm/orchestrator/scorchestrator/SCOrchestrator.py
\--status --components=openstack-keystone

Check that users can log in to the IBM Cloud Orchestrator user interfaces.

1054

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Re-configuring an existing Nova network

This topic describes how you can re-configure an existing Nova network.

How to re-configure an existing Nova network

It is only possible to re-configure a network through deleting the existing network
and recreating it with the new values that needs to change. Changing the
configuration of a network that is already up and restarting the OpenStack services
might lead to system failure.

Troubleshooting a VMware region

There are some known problems and limitations that might occur in a VMware
region.
Cannot find attached volume after volume-attach:
The nova volume-attach can be used to attach a volume to an instance.
Sometimes, the volume-attach command runs successfully, but when you run
the fdisk -l, you cannot find the attached volume. After you restart the virtual
machine, the volume is found. It is an known issue for a VMware hosted
system. There are some workarounds you can use to discover the attached volume
without rebooting the guest operating system, such as logging into the guest
operating system and running the following command:
echo "- - -" > /sys/class/scsi_host/host#/scan

A VMware instance is shut down every time it is restarted:

OpenStack has a feature where power states are synced between the OpenStack
database and the managed hypervisors. If OpenStack records a virtual machine as
shut down, it ensures that the virtual machine is shut down on the hypervisor as
well. So, if a cluster inside an vCenter is managed by more than one OpenStack
VMware Region, when a virtual machine is started from a VMware Region, the
other region tries to stop it. To avoid this, make sure that each cluster of vCenter is
managed by only one OpenStack VMware Rregion. When you configure a VMware
Region, consider the following issues:
v You cannot share a vCenter cluster across IBM Cloud Orchestrator installations.
When you do, and then stop a virtual machine, whenever you start it, the other
OpenStack ensures that it is stopped within 60 seconds.
v You cannot host the managed-from environments on the managed-to vCenter.
v Avoid out of band operations.
A VMware instance is shut down every time it is restarted:
If during a VMware discovery, you encounter an Header Line too Long error in
the Nova /var/log/nova/discovery.log (the message is visible in the
discovery.log only if you set to debug the log level of Nova VMware discovery),
the workaround is to change glance-api.conf to add following option:
max_header_line = 1638400

and restart the glance-api service, then rerun the discovery.

Chapter 12. Troubleshooting

1055

Troubleshooting PowerVC region

You may encounter problems with PowerVC such as being unable to create or
delete volumes, errors connecting to qpid, or encountering authentication errors
regarding staging user/tenant.
Log files for PowerVC are available at the following location: /var/log/powervc/
v glance-powervc.log
v neutron-powervc.log
v nova-powervc.log
v cinder-powervc.log
The logging level of each log is controlled by the conf file of the base component.
Unable to create or delete volumes in PowerVC
When the openstack-cinder-powervc service fails, due to lack of ssl
certificate or another issue, this can also cause the openstack-cindervolume service to fail. Restart the service on the PowerVC Region Server
service openstack-cinder-volume restart to fix this.
Errors connecting to qpid
When the PowerVC server had a lot of requests in quick succession, the
qpid service on the PowerVC server might fail. To solve the issue restart
the service by running the following command on the PowerVC server:
service qpidd restart

Authentication errors communicating with either keystone of PowerVC

v Confirm OpenStack credentials are correct
v Confirm PowerVC credentials are correct
v Confirm PowerVC qpid password is correct
v Confirm PowerVC SSL certificate is located at /etc/pki/tls/certs/
powervc.crt on the PowerVC Region Server
v Confirm that the PowerVC can communicate with the PowerVC server
by the means specified by the ssl certificate. This can be by IP address,
host name or FQDN, depending on the installation of PowerVC. This is
resolved by either ensuring that both PowerVC Region Server and
PowerVC server are setup on the same DNS server correctly.
Alternatively, put an appropriate entry in the /etc/hosts file of the
PowerVC Region Server.
Authentication errors regarding staging user/tenant
Confirm that the staging user is a member of the staging tenant.
Volume ids of attached volumes are incorrect
Workload Deployer attach disk operations fails, even if the disk is attached
and Horizon has problems displaying the instances that have volumes
attached.
Confirm that the tenant used to authenticate with keystone is the same
tenant used as the staging tenant.
Live Migration does not occur
v When performing a live migration, the log file states that the resource
monitoring and control is down on the virtual machine. The resource
monitoring and control is a program that hardware management console
uses to communicate with the LPARS. This is standard on AIX
deployments, but is not on pLinux.

1056

IBM Cloud Orchestrator 2.4.0.2: User's Guide

v Confirm the resource monitoring and control is running on the virtual

machine to be migrated. This can be confirmed by an OK health status
by the nova show command or by viewing the PowerVC user interface.
If the resource monitoring and control is not running on an AIX
deployment, reset it. The image must also be recaptured as the resource
monitoring and control often gets disabled by the Network Installation
Manager deployment process.
# /usr/sbin/rsct/bin/rmcdomainstatus -s ctrmc

-check status

Stopping and starting resource monitoring and control without

erasing configuration:
- # /usr/sbin/rsct/bin/rmcctrl -z - Stops the daemons
- # /usr/sbin/rsct/bin/rmcctrl -A - Adds entry to /etc/inittab
and it starts the daemons
- # /usr/sbin/rsct/bin/rmcctrl -p - Enables the daemons for
remote client connections
If it is a pLinux image, there are instructions on how to install the
resource monitoring and control in the PowerVC documentation.
Unable to change passwords on AIX Activation Engine enabled images via the
Self-Service Catalog
The self service catalog does not currently support changing the passwords
at deploy time for the AIX Activation Engine enabled images.
Volume Resize Operations do not occur or fail
SSP backed storage does not support resize of disk:
2014-11-11 04:49:34.916 4750 ERROR oslo.messaging.rpc.dispatcher [-]
Exception during message handling: Get error: RPCException: Cinder API error:
NV-37CDE0F The host 228b02eb0e47e611e4b5060000c9f82a76 for boot volume
991b9732-041d-4dab-8ef8-75006216920d does not support extend volume.

Shared Volume Controller FlashCopy operations can only occur serially per
image; if it is doing a copy or extending operation on a boot volume, you
cannot invoke a new operation to make changes to the volume. You can
check the Shared Volume Controller UI to see whether a flashcopy is in
progress to the target volume or the current target volume is being
extended:
2014-11-11 01:24:58.006 2095 TRACE nova.openstack.common.loopingcall
ResizeError: Get error: PVCExpendvdiskFCMapException: Flashcopy is in
progress for boot volume, volume size didnt change. Please try again later.
(HTTP 409) (Request-ID: req-29350427-32b3-4721-baca-504c5216b041)
during resizing the instance in the PowerVC

Changing the PowerVC username and password on the Region Server if the
PowerVC username or password changes
1. On the Region Server, edit the following file:
/etc/powervc/powervc.conf

Note: Take a backup of the file before making any changes.

2. Navigate to [powervc] and locate admin_user and admin_password.
3. Change the username and password using admin_user and
admin_password.
Note: The password must be encrypted so use openstack-obfuscate
<password> to generate.
4. Click Save.
Chapter 12. Troubleshooting

1057

5. Restart the following services as specified in Post PowerVC Region

Server installation tasks on page 50:
v service openstack-glance-powervc restart
v service openstack-neutron-powervc restart
v service openstack-nova-powervc restart
v service openstack-cinder-powervc restart
v service openstack-cinder-volume restart
Unable to attach volumes to Instances on Shared Storage Pool backed
environment
Volume attach on Shared Storage Pool backed environments require that
the RMC (Resource Monitoring and Control software) is installed and
running on deployed instances. If the particular instance that you are
deploying never appears to have RMC running, in other words the health
of the virtual machine is warning, it will be necessary to reset it (relevant to
all operating system types) or install it; if it has not been installed already
(relevant to pLinux). AIX should have RMC included by default.
To install the RMC for pLinux follow this link (http://www.ibm.com/
support/customercare/sas/f/lopdiags/home.html) and install the Service
and Productivity Tools.
To reset RMC perform the following commands on a running instance and
then recapture using the usual process:
# /usr/sbin/rsct/bin/rmcctrl -z
# /usr/sbin/rsct/bin/rmcctrl -A
# /usr/sbin/rsct/bin/rmcctrl -p

After these three commands are executed the status of the virtual machine
in the PowerVC UI should change from warning to OK, but this may take
several minutes.
PowerVC intermittent volume attach issues on Workload Deployer
Intermittently Workload Deployer will return the pattern status of failed
against a AIX deployment that had a disk attached. The error returned as
part of the disk attach script in Workload Deployer will state the following
or similar:
*** basic validation of input
*** validation done
*** searching for uninitialized disk of size 1GiB
new pvs =
pvtouse=
ERROR : no free pv found of size 1

But the final status of the virtual machine itself will be green, what has
happened is that PowerVC had returned that the status of the volume was
in-use when in reality it had not been attached yet. This caused the
Workload Deployer verification of the attachment to fail. In all cases where
this issue occurs, the volume is correctly attached and the only side effect
is that the overall status of the pattern is failed. The virtual machine is
fully functional.
rstrip error in nova-powervc.log and some actions such as starting or stopping
the virtual machine may not be responsive
In the event that the following error is in the nova-powervc.log:
2014-12-17 02:57:10.348 26453 ERROR powervc.nova.driver.compute.manager [-]
Exception: Exception: NoneType object has no attribute rstrip

1058

IBM Cloud Orchestrator 2.4.0.2: User's Guide

stop and start the services on the PowerVC Region Server using
SCOrchestrator.py.
PowerVC Region Server does not support secure connection to PowerVC server
with mixed-case or uppercase host name
This problem affects only secure connections; insecure connections are
unaffected. The following error is displayed:
Host "hostname" does not match x509 certificate contents: CommonName "hostNAME", subjectAltName "DNS:hostNAME, DNS IP"

To fix this problem, complete the following steps:

1. Reconfigure the PowerVC server so that the host name is specified in
lowercase letters. Include the fully qualified domain name.
2. Reconfigure the PowerVC application by using the powervc-config
command.
3. Run the powervc-replace-cert command to generate a new
powervc.crt file that is based on the new host name.
4. Restart the httpd service on the PowerVC server.
5. Replace the powervc.crt file on the PowerVC Region Server with the
new powervc.crt file generated in step 3.
6. Restart the PowerVC services on the PowerVC Region Server.

Troubleshooting Workload Deployer

You can troubleshoot problems in the Workload Deployer component

Failure to deploy a virtual system or application when a linked

clone is enabled
There might be a failure to deploy a virtual system or a virtual application when a
linked clone is enabled.
This happens when you use a flavor with key VMWareUsedLinkedClones=true. The
deployment fails if the disk defined in flavor is not the same as the disk size in the
VMware template. This is a VMware limitation that does not allow you to resize
the linked disk.

Increasing the default timeout if hypervisor fails

If a hypervisor goes into a failure state, it might mean that you need to increase
the Workload Deployer timeout value.
You can increase the default timeout value that determines how long Workload
Deployer waits for the background hypervisor data to be obtained. The value can
be configured inside the following file: /opt/ibm/rainmaker/purescale.app/
private/expanded/ibm/rainmaker.cloud-4.0.0.1/config/zero.config
The entry that requires a value change is: /config/cloudburst/vmsupport/
timeoutmsOPENSTACK.
The value is specified in milliseconds. The default value is 3600000 (= 1 hour).

Workload Deployer gets easily in an inconsistent state

When the unexpected outage occur of the Workload Deployer component there is a
possibility that the Workload Deployer databases could be in an inconsistent state.
Chapter 12. Troubleshooting

1059

The DB2 diagnostic logs will then contain error entries for RAINMAKE and/or
STORHOUS databases indicating the problem and providing solution information. At
the same time, the Workload Deployer component will not be able to start
successfully, reporting database connectivity errors in the trace logs.
Sample error entry from the DB2 diagnostic log showing inconsistent state for the
database RAINMAKE:
2014-10-01-11.46.34.244536-240 E560597E650
LEVEL: Error
PID
: 28925
TID : 140323141445376 PROC : db2sysc 0
INSTANCE: db2inst1
NODE : 000
DB
: RAINMAKE
APPHDL : 0-3751
APPID: 172.21.29.101.44732.141001163839
AUTHID : DB2INST1
HOSTNAME: cil021029097.cil021029.ibm.com
EDUID
: 16732
EDUNAME: db2agent (RAINMAKE) 0
FUNCTION: DB2 UDB, base sys utilities, sqledint, probe:2535
MESSAGE : SQL1015N The database is in an inconsistent state.
DATA #1 : String, 91 bytes
Crash Recovery is needed.
Issue RESTART DATABASE on this node before issuing this command.

DB2 command sample output that will be printed if the database is in an

inconsistent state:
[db2inst1@external-db ~]$ db2 connect to rainmake
SQL1015N The database is in an inconsistent state.
[db2inst1@external-db ~]$ db2 connect to storhous
SQL1015N The database is in an inconsistent state.

SQLSTATE=55025
SQLSTATE=55025

Sample error message from the Workload Deployer component trace log in case of
problems with inconsistent database:
CWZCO1014E: Could not retrieve resources: [pdq][0][2.7.116]
CWPZC9001E: Could not obtain Connection from org.apache.commons.dbcp.PoolingDataSource;
Caused by: com.ibm.db2.jcc.am.SqlException: DB2 SQL Error: SQLCODE=-1015, SQLSTATE=55025,
SQLERRMC=null, DRIVER=4.14.113 com.ibm.pdq.runtime.exception.DataRuntimeException:
[pdq][0][2.7.116] CWPZC9001E: Could not obtain Connection from
org.apache.commons.dbcp.PoolingDataSource;
Caused by: com.ibm.db2.jcc.am.SqlException: DB2 SQL Error: SQLCODE=-1015, SQLSTATE=55025,
SQLERRMC=null, DRIVER=4.14.113

The Workload Deployer component logs location when the error message from
above could be present:
/drouter/ramdisk2/mnt/raid-volume/raid0/logs/trace/trace.log
/drouter/ramdisk2/mnt/raid-volume/raid0/usr/servers/kernelservices/logs/trace.log.*
/drouter/ramdisk2/mnt/raid-volume/raid0/usr/servers/storehouse/logs/trace.log.*

Solution:
In case of database inconsistent state, you must run the following commands on
the DB2 node:
su - db2inst1 -c db2 connect to rainmake; db2 restart database rainmake
su - db2inst1 -c db2 connect to storhous; db2 restart database storhous

1060

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Troubleshooting Business Process Manager

There are some known issues and limitations that might occur when you are
working with Business Process Manager.

Log tracing
In Business Process Manager, tracing is switched off by default. If you must
troubleshoot or debug any issues, switch tracing on.

Visible security-sensitive information

The SCOrchestrator toolkit saves in the log file all parameters passed by other
toolkits used by runbooks. If these parameters contain security-sensitive
information, they are visible in the <path to BPM profile>/log/
SingleClusterMemeber1/SystemOut.log file.
To disable logging from the SCOrchestrator toolkit, perform the following steps:
1. Create a script file named disableLogging.py with the following content:
AdminTask.setTraceSpecification([-persist true -traceSpecification *=info:WLE.wle_javascript=audit ]);
AdminConfig.save();

2. Run the following command on Central Server 2 from the directory where file
has been saved:
<path to BPM profile>/bin/wsadmin.sh -host `uname -n` -username admin
-password <passw0rd> -f disableLogging.py

To re-enable logging in the SCOrchestrator toolkit, perform the following steps:

1. Create a script file named enableLogging.py with the following content:
AdminTask.setTraceSpecification([-persist true -traceSpecification *=info ]);
AdminConfig.save();

2. Run the following command on Central Server 2 from the directory where file
has been saved:
<path to BPM profile>/bin/wsadmin.sh -host `uname -n` -username admin
-password <passw0rd> -f enableLogging.py

Database size increases continuously

The size of the Performance Data Warehouse Database increases continuously (>
100 GB) when IBM Cloud Orchestrator is running and finally results in out of
space errors.
The growth of the Performance Data Warehouse Database is caused by error
messages written to the table LSW_DATA_TRANSFER_ERRORS similar to the following
message:
undefined tracking group with external ID 5cde1ff9-d1ab-4a88-8810-b0e7dcbe571e

Solution:
1. Open the Business Process Manager Process Designer.
2. Open Process Apps or Toolkits, for example:
SCOrchestrator_Support_vSys_Toolkit (SCOVSYS)

3.

Click File > Update Tracking Definitions.

Chapter 12. Troubleshooting

1061

Central Server 2 installation fails

The installation of Central Server 2 fails and in the log file there are chef errors
when installing Business Process Manager.
Solution:
To resume the installation, remove Business Process Manager from Central Server
2. For information about removing Business Process Manager, see the Business
Process Manager section of the IBM Knowledge Center. After Business Process
Manager is removed, you can resume the installation with following command:
ds job-execute -r TRUE

Troubleshooting the Public Cloud Gateway

Use this section to resolve any issues that you may encounter when using the
Public Cloud Gateway.
Logs are stored in the /var/log/pcg.log.
The Public Cloud Gateway uses log4j logging. The log4j.properties file is
located in the /opt/ibm/pcg/etc directory.
For more information about the properties in the log4j.properties file, see the
documentation on the Log4j web site: http://logging.apache.org/log4j

Loss of functionality in Public Cloud Gateway cloud groups

Loss of functionality may occur in Public Cloud Gateway cloud groups in IBM
Cloud Orchestrator, where there has been heavy load on the Public Cloud Gateway
cloud groups.
Symptom
As stated in description.
Cause This is due to exceeding the Amazon Web Service (AWS) API Request Rate
limit. The Public Cloud Gateway has addressed this issue by introducing a
caching mechanism.
Solution
See Configuring caching on page 691.
Related tasks:
Configuring the Public Cloud Gateway on page 666
The Public Cloud Gateway is deployed as part of the IBM Cloud Orchestrator
installation on the Central Server 2 machine. However, the Public Cloud Gateway
is not enabled by default and certain updates to the configuration files are required
before you can use the Public Cloud Gateway.

1062

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Region names displayed incorrectly in the Virtual Image page

A known issue exists where IBM Cloud Orchestrator removes the name after an
_ in the region name when registering images.
Symptom
EC2-US-WEST_NORTHERN-CA and EC2-US-WEST_OREGON regions are displayed as
EC2-US-WEST when registering an image. This error prevents you from
selecting images from both regions.
Solution
1. Edit /opt/ibm/pcg/etc/config.json on Central Server 2 and replace _
(underscore) in region names with a (dash).
2. Restart the Public Cloud Gateway to allow the changes to take effect:
service pcg restart

3. Log in to IBM Cloud Orchestrator and wait for the new regions to
display. Once the images are displayed, delete the old
EC2-US-WEST_NORTHERN-CA and EC2-US-WEST_OREGON cloud groups and
hypervisors . You can also delete any registered images that belong to
these regions.
4. Log in to the Central Server 2 and run the following command:
keystone endpoint-list

and identify the old endpoints by their region name.

5. Delete the old endpoints for EC2-US-WEST_NORTHERN-CA and
EC2-US-WEST_OREGON, by running the following command:
keystone endpoint-delete <endpoint-id>

Note: Be careful not to delete any valid endpoints.

6. Images can now be registered for both regions.
Related tasks:
Configuring the Public Cloud Gateway on page 666
The Public Cloud Gateway is deployed as part of the IBM Cloud Orchestrator
installation on the Central Server 2 machine. However, the Public Cloud Gateway
is not enabled by default and certain updates to the configuration files are required
before you can use the Public Cloud Gateway.

Unable to connect to a public cloud due to missing

credentials
In the Public Cloud Gateway, you might receive the error Unable to connect to
public cloud due to missing credentials.
Symptom
As stated in description.
Cause This is due to tenants or projects being present in IBM Cloud Orchestrator
that are not accounted for in the credentials.json file.
Solution
You can resolve this problem in one of the following ways:
v Add credentials for each tenant in IBM Cloud Orchestrator to the
credentials.json file.
v Add credentials for a specific tenant by ID in IBM Cloud Orchestrator to
the credentials.json file.

Chapter 12. Troubleshooting

1063

v Add credentials, where the tenantName is * as stated in step 5 in the

related configuring topic. This ensures that these credentials are applied
to each tenant that is not explicitly stated in credentials.json file.
Related tasks:
Configuring the Public Cloud Gateway on page 666
The Public Cloud Gateway is deployed as part of the IBM Cloud Orchestrator
installation on the Central Server 2 machine. However, the Public Cloud Gateway
is not enabled by default and certain updates to the configuration files are required
before you can use the Public Cloud Gateway.

Unable to deploy instance to non-IBM supplied OpenStack

Unable to deploy an instance to non-IBM supplied OpenStack with error:
"
org.apache.http.impl.client.DefaultRequestDirector [WARN] Authentication
error: Unable to respond to any of these challenges: {}".
While Public Cloud Gateway might appear to behave normally, the hypervisors are
present, the cloud group exists, registering images is successful, the following is
shown in the log file when deploying an instance to non-IBM supplied OpenStack.
[2013-08-01 09:00:33,607] org.apache.http.impl.client.DefaultRequestDirector [WARN]
Authentication error: Unable to respond to any of these challenges: {}
[2013-08-01 09:00:33,621] com.ibm.ccs.publiccloud.service.actions.ServerActions [ERROR]
Unable to deploy Instance com.ibm.ccs.publiccloud.broker.exception.ServiceException
.
.

Caused by: com.amazonaws.AmazonClientException: Unable to unmarshall error response
(Content is not allowed in prolog.)
.
.

Caused by: org.xml.sax.SAXParseException: Content is not allowed in prolog.

Solution:
The credentials used to connect to non-IBM supplied OpenStack have read but not
write permissions. The Public Cloud Gateway requires credentials with
permissions to deploy instances.

Inconsistencies in deployed instance names

When server instances are deployed on non-IBM supplied OpenStack, the names
that are given to the instances in the non-IBM supplied OpenStack differ from the
names that are given to the instances in IBM Cloud Orchestrator.
This is a known issue in the Amazon EC2 API implementation in OpenStack
versions before the Grizzly release.
For more information about this known issue, see the following link:
https://bugs.launchpad.net/nova/+bug/1096821

1064

IBM Cloud Orchestrator 2.4.0.2: User's Guide

MAC address field is empty

No information is displayed for the MAC address field when viewing non-IBM
supplied OpenStack or Amazon EC2 virtual system instances.
Symptom
Once a non-IBM supplied OpenStack or Amazon EC2 virtual system
instance is deployed, open the Virtual System Instances panel, by clicking
PATTERNS > Instances > Virtual System Instances (Classic). You see that
no information is displayed for the MAC address field.
Solution
This information is not available when using the Public Cloud Gateway.

Quota troubleshooting
Resolve any quota issues that you encounter when using the Public Cloud
Gateway.
Default quota is not defined large enough
Without any customization, a default quota definition exists in
the config.json. There are situations in which this default quota definition
is too small.
Resolution: Either create a project level quota in the Quota tab of the
Project page in the Administration user interface or increase the default
quota definition in config.json.
Project quota definition is too small
Resolution: If a project level quota definition exists, the values can only be
changed in the Quota tab of the Project page in the Administration user
interface.
Existing virtual machine instances already consume more resources than the
quota allows
Resolution: Count the number of instances, cores, RAM, and volume usage
and update the corresponding quota values. Volumes is the sum of the VM
instance volume and the additional disks. There is a gigabytes value in the
quotas which defines the largest possible virtual machine instance possible.
It is possible that you have reached this limit.
Too many key-pairs already exist
Resolution: Key pairs are stored on a per project base post-fixed with the
project ID. Sum up all the key pairs that have the same project ID and
adjust the quota definition for key pairs accordingly.
Too much storage is already consumed than is defined in the quota
Resolution: Volumes are the sum of the virtual machine instance volume
and the additional disks. Adjust the quota definition for volumes
accordingly
Provisioning failed even though quota has not been reached yet
There might be situation where the capacity of the region (EC2, SoftLayer
or NIOS) is already exhausted prior to the defined quotas.
Resolution:
v Check if you have set the quota for the region and projects higher than
the capacity of the region. Either lower the quota for the related projects
or increase the capacity of the region.
Chapter 12. Troubleshooting

1065

v Check if you have additional out-of-bound-created resources within the

region. If so, make sure, using ACL, that these resources are not visible
to the user ID you have configured for the region access in
credentails.json.

Failure to generate admin token

The Public Cloud Gateway fails with Unable generate admin token error.

Problem
The Public Cloud Gateway startup fails with Unable generate admin token
and a HybridUnauthorizedException errors.
During startup of Public Cloud Gateway an admin token is generated based on the
following configuration information in the etc directory of the Public Cloud
Gateway:
* admin.json
* config.json

Admin.json content:
{
"auth":{
"passwordCredentials":{
"username":"xxxx",
"password":"yyyyy"
},
"tenantName":"zzzz",
"domainName": "ddddd"
}
}

The username must be a user ID which has admin rights. The password must be
encrypted via the encryptPassword.sh. The tenantName must be set to the tenant
name of the admin user. The domainName is optional and defaults to the Default
domain. Set domainName to the domain of the admin user.
Note: Required if the user is in a non-default domain.

Resolution
Make sure the values in admin.json match to your admin userid in the system.
Config.json content:
"auth":{
"provider":"keystone",
"service_url":"http://KeystoneHost:5000",
"admin_url":"http://KeystoneHost:35357"
}

If you manually changed the content of the service_url or the admin_url, the
admin token cannot be created.
Make sure that the KeystoneHost is set to the host name where keystone is
installed in your IBM Cloud Orchestrator environment. During installation the
values are configured based on your topology selection.

1066

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Time-outs during resource modification processing

For regions managed by the Public Cloud Gateway there is a possibility that
time-outs might happen during: Create, Delete, Attach, Detach of a resource.
Root cause is that there are multiple levels of timeout handling in such a
management scenario.
Public Cloud Gateway is frequently updating its internal caches with the live data
from the remote clouds. These refresh times are configurable through configuring
caching (for details, refer to: Configuring caching on page 691).
The management workflows which orchestrate the modification actions have also a
timeout handling. As default they query the status of the modification action once
per minute and do it for a certain amount of retries. The retry value is configurable
in the related toolkits.
Depending on how the cache refresh in the Public Cloud Gateway is configured
related to the workflow retries, there might be situations were the workflow does
not wait long enough for a status change depending on the time the modification
action requires.
In Public Cloud Gateway scenarios the time a remote request lasts might have a
huge variation time depending on:
v The size of the resource that should be modified.
v The remote cloud that is the target of the modification (Amazon AWS EC2 or
SoftLayer).
v The time of the day the request is performed.
v The day within a week or month the request is performed.
The retries within the workflows are defaulted based on variation tests. There
might be situations were these values are too small.
If such a situation happens that the retry count is too short, you would see
messages in the workflow log that the workflow waited for all the retries without
success.
Resolution:
Check in the remote cloud if the intended modification action was completed
successful. If this is true ignore the workflow error. If the modification action was
not successful rerun the request / offering. If the situation happens frequently, get
in touch with IBM Customer Support to get instructions to increase the retry count
in the workflows.

Problem configuring privateNetworkOnly on Amazon EC2

Subnets
This topic describes a problem that might occur configuring privateNetworkOnly
on Amazon EC2 subnets. Amazon provided a new out of the box feature to auto
assign public IP addresses on a subnet base. This feature allows to control on a
subnet base if a public IP address should be assigned. The feature is available for
defautlVPC and non-default VPC as subnets are assigned through the VPC and
availability zone.

Chapter 12. Troubleshooting

1067

Symptom
The problem occurs configuring privateNetworkOnly according to what
documented at Configuring subnets and security groups in a non-default VPC
region on page 702.
During provisioning the result is not as expected, whether a public IP address is
assigned or not.

Cause
Late in 2014 Amazon added new out of the box support for auto assign public
IP address on the subnet configuration for Default and non-Default VPC.
If you see a Modify Auto-Assign Public IP button on the subnets page in your
VPC Dashboard, you might face the problem.
If Auto-assign Public IP is set to yes, this setting all the time takes precedence
over what you configured in Public Cloud Gateway.

Solution
The Auto-assign Public IP flag on the subnet used for provisioning must be set to
no for default or non-default VPC.
Setting the Auto-assign Public IP flag on the subnet to yes has all time precedence
over the Public Cloud Gateway related configuration.
Related concepts:
Configuring subnets and security groups in a non-default VPC region on page
702
You can configure subnets and security groups in a non-default VPC region.

Debugging image templates

When you build new images from the base images available in the remote clouds,
you must take some precautions to allow the images to support login via user ID
and password.
Problem
The provisioned virtual machine from an image template is not accessible
via the specified credentials. This problem might happen for the following
reasons:
v cloud-init or cloudbase-init is not installed.
v cloud-init or cloudbase-init is not configured for root and password
login.
v The SCP-INIT extensions provided by Public Cloud Gateway are not
installed on Workload Deployer images.
v The remote clouds have strict default password rules and the password
provided in the DeploySingleServer offering is not compliant with the
rules in the image.
Solution
Perform the following steps:
1. Add a debug user to the image so that you can access the image after
provisioning if problems occur. Remove the debug user in the final
version of the image.

1068

IBM Cloud Orchestrator 2.4.0.2: User's Guide

2. Make sure that you performed all the image setup steps for the
deployment scenario that you chose.
3. Check the password rules that are active on the base image and ensure
that the provided password is compliant.
4. Make sure that cloud-init or cloudbase-init is installed and
configured, and that the Public Cloud Gateway provided extensions are
installed.
5. For Windows provisioning, make sure that all the required ports are
reachable from the Workload Deploy node.

Deploying an instance with an additional disk to SoftLayer fails

due to timeout
Unable to deploy an instance with an additional disk to SoftLayer fails with error:
"java.net.SocketTimeoutException: Read timed out".
When a new instance is deployed with an additional disk, Public Cloud Gateway
waits until the virtual machine is running before it attaches the disk. Depending on
the load of the cloud, this may take up to several minutes on SoftLayer, during
which the provisioning workflow may run in a timeout.
Solution:
You can increase the socket timeout by following these steps:
1. Log into Websphere console as bpm_admin at https://<host>:9043/admin.
2. Navigate to Servers > All Servers > SingleClusterMember1 > Server
Infrastructure >Java and Process Management >Process definition
>Additional Properties > Java Virtual Machine > Custom properties.
3. Add new property: vmm_OpenStack_SocketTimeout and set it to 3600000 (1
hour).
4. Save and restart the bpm server by running service bpm restart on the
command line.

Chapter 12. Troubleshooting

1069

1070

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Accessibility features for IBM Cloud Orchestrator

Accessibility features help a user who has a physical disability, such as restricted
mobility or limited vision, to use software products successfully. The major
accessibility features of IBM Cloud Orchestrator are described in this topic.

Accessibility features
The following list includes the major accessibility features in IBM Cloud
Orchestrator:
v Keyboard-only operation
v Interfaces that are commonly used by screen readers
v Keys that are discernible by touch but do not activate just by touching them
v Industry-standard devices for ports and connectors
v The attachment of alternative input and output devices
Note: The default configuration of JAWS screen reader does not read tooltips.
JAWS users must enable their current mode to read tooltips by selecting Utilities >
Settings Center > Speech Verbosity > Verbosity Level > Configure Verbosity
Levels.
User documentation is provided in HTML and PDF format. Descriptive text is
provided for all documentation images.
The knowledge center, and its related publications, are accessibility-enabled.

Related accessibility information

You can view the publications for IBM Cloud Orchestrator in Adobe Portable
Document Format (PDF) using the Adobe Reader. PDF versions of the
documentation are available in the knowledge center.

IBM and accessibility

See the IBM Human Ability and Accessibility Center for more information about
the commitment that IBM has to accessibility.

Copyright IBM Corp. 2013, 2015

1071

1072

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Notices
This information was developed for products and services that are offered in the
USA.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
United States of America
For license inquiries regarding double-byte character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send
inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM websites are provided for
convenience only and do not in any manner serve as an endorsement of those

Copyright IBM Corp. 2013, 2015

1073

websites. The materials at those websites are not part of the materials for this IBM
product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating

1074

IBM Cloud Orchestrator 2.4.0.2: User's Guide

platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
Portions of this code are derived from IBM Corp. Sample Programs.
Copyright IBM Corp. 2013, 2015. All rights reserved.

Programming interface information

This publication primarily documents information that is NOT intended to be used
as Programming Interfaces of IBM Cloud Orchestrator. This publication also
documents intended Programming Interfaces that allow the customer to write
programs to obtain the services of IBM Cloud Orchestrator. This information is
identified where it occurs, either by an introductory statement to a chapter or
section or by the following marking: Programming Interface information.

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the web at www.ibm.com/legal/
copytrade.shtml.

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the following
terms and conditions.

Applicability
These terms and conditions are in addition to any terms of use for the IBM
website.

Personal use
You may reproduce these publications for your personal, noncommercial use
provided that all proprietary notices are preserved. You may not distribute, display
or make derivative work of these publications, or any portion thereof, without the
express consent of IBM.

Commercial use
You may reproduce, distribute and display these publications solely within your
enterprise provided that all proprietary notices are preserved. You may not make
derivative works of these publications, or reproduce, distribute or display these
publications or any portion thereof outside your enterprise, without the express
consent of IBM.

Notices

1075

Rights
Except as expressly granted in this permission, no other permissions, licenses or
rights are granted, either express or implied, to the publications or any
information, data, software or other intellectual property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its
discretion, the use of the publications is detrimental to its interest or, as
determined by IBM, the above instructions are not being properly followed.
You may not download, export or re-export this information except in full
compliance with all applicable laws and regulations, including all United States
export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE
PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING
BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

IBM Online Privacy Statement

IBM Software products, including software as a service solutions, (Software
Offerings) may use cookies or other technologies to collect product usage
information, to help improve the end user experience, to tailor interactions with
the end user or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings
can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific
information about this offerings use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use
session and persistent cookies that collect each users user name, or other
personally identifiable information for purposes of session management, enhanced
user usability, single sign-on configuration. These cookies cannot be disabled.
If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.
For more information about the use of various technologies, including cookies, for
these purposes, See IBMs Privacy Policy at http://www.ibm.com/privacy and
IBMs Online Privacy Statement at http://www.ibm.com/privacy/details the
section entitled Cookies, Web Beacons and Other Technologies and the IBM
Software Products and Software-as-a-Service Privacy Statement at
http://www.ibm.com/software/info/product-privacy.

1076

IBM Cloud Orchestrator 2.4.0.2: User's Guide

Glossary
This glossary includes terms and definitions for
IBM Cloud Orchestrator.
The following cross-references are used in this
glossary:
v See refers you from a term to a preferred
synonym, or from an acronym or abbreviation
to the defined full form.
v See also refers you to a related or contrasting
term.
To view glossaries for other IBM products, go to
www.ibm.com/software/globalization/
terminology (opens in new window).

A
account code
A code that uniquely identifies an
individual, billing, or reporting entity
within chargeback and resource
accounting.
account code conversion table
An ASCII text file that contains the
definitions that are required to convert
the identifier values defined by the
account code input field to the
user-defined output account codes.
account report
A report that is used to show account
level information for usage and charge.
audit data
A data record that contains information
about specific types of user activity,
security events, and configuration
changes in the product and in the cloud.
availability zone
A logical group of OpenStack Compute
hosts. It provides a form of physical
isolation and redundancy from other
availability zones, such as by using
separate power supply or network
equipment.

Copyright IBM Corp. 2013, 2015

1077

B
Bill program
A program that performs cost extensions
within SmartCloud Cost Management and
summarizes cost and resource utilization
by account code. The Bill program uses
the rate code table that is assigned to the
client to determine the amount to be
charged for each resource consumed.
building block
The model of an image that is created by
combining models of a base operating
system and software bundles. Each
building block contains a semantic and
functional model that describes the
contents of the components, for example,
the installed products, supported
operating systems, prerequisites, and
requirements.
business object
A software entity that represents a
business entity, such as an invoice. A
business object includes persistent and
nonpersistent attributes, actions that can
be performed on the business object, and
rules that the business object is governed
by.
business process
A defined set of business activities that
represent the required steps to achieve a
business objective. A business process
includes the flow and use of information
and resources.

C
chargeback identifier
A label, which is often tied to an
algorithm or set of rules, that is not
guaranteed to be unique, but is used to
identify and distinguish a specific
chargeback item or chargeback entity
from others.
cloud group
A collection of hypervisors from a single
vendor. See availability zone.
compute node
A node that runs a virtual machine
instance, which provides a wide range of
services, such as providing a development
environment or performing analytics.

1078

IBM Cloud Orchestrator 2.4.0.2: User's Guide

consolidation process
A process during which the data
collectors process the nightly accounting
and storage files that were created by the
data collection scripts and produce an
output CSR file.
conversion mapping
An entry in a mapping table which allows
you to map identifiers to accounts or
other identifiers.
custom node
A virtual image part that provides an
unconfigured node for a pattern that has
a deployment manager or a control node
as its base.

E
exception file
A file that contains a list of records with
identifier names that do not have a
matching Parameter IdentifierName
attribute value.
exception processing
A process in which the system writes all
records that to do match an entry in the
account code conversion table to an
exception file.

H
human service
An activity in the business process
definition that creates an interactive task
that the process participants can perform
in a web-based user interface.
hypervisor
Software or a physical device that enables
multiple instances of operating systems to
run simultaneously on the same
hardware.

K
kernel The part of an operating system that
contains programs for such tasks as
input/output, management and control of
hardware, and the scheduling of user
tasks.

parameter (parm)
A value or reference passed to a function,
command, or program that serves as
input or controls actions. The value is
supplied by a user or by another program
or process.

service operation
A custom operation that can be run in the
context of the data center. These
operations are typically administrative
operations and are used to automate the
configuration. Service operations can also
be used to enhance the catalog of
available services with extra functionality.

parm

See parameter.

performance counter
A utility that provides a way for software
to monitor and measure processor
performance.
primary key
In a relational database, a key that
uniquely identifies one row of a database
table.
process application
A container in the Process Center
repository for process models and
supporting implementations. A process
application typically includes business
process definitions (BPDs), the services to
handle implementation of activities and
integration with other systems, and any
other items that are required to run the
processes. Each process application can
include one or more tracks.
proration
A process that distributes the overall or
individual resources of an account and
the cost of those resources across multiple
accounts at a specified percentage.
proration table
An ASCII text file that defines the
identifier values and rate codes that are
used in the proration process.

R
rate code
The identifier of a rate that is used to link
a resource unit or volume metric with its
charging characteristics.
rate group
A group of rate codes that is used to
create rate subtotals in reports, graphs,
and spreadsheets.
registry
A repository that contains access and
configuration information for users,
systems, and software.

shared service
A predefined virtual application pattern
that is deployed and shared by multiple
application deployments in the cloud,
including virtual applications, virtual
systems, and virtual appliances.
software bundle
A collection of software installation files,
configuration files, and metadata that can
be deployed on a virtual machine
instance.

T
toolkit
A container where artifacts can be stored
for reuse by process applications or other
toolkits.

V
virtual application
A complete set of platform resources that
fulfill a business need, including web
applications, databases, user registries,
messaging services, and transaction
processes. A virtual application is defined
by a virtual application pattern. See also
virtual application pattern.
virtual application pattern
A pattern that defines the resources that
are required to support virtual
applications, including web applications,
databases, user registries, and more.
These patterns are the deployment unit
for a virtual application. See also virtual
application.
virtual machine (VM)
An instance of a data-processing system
that appears to be at the exclusive
disposal of a single user, but whose

Glossary

1079

functions are accomplished by sharing the

resources of a physical data-processing
system.
virtual system
A collection of virtual machines.
virtual system instance
The virtual environment that runs on a
hypervisor in the cloud.

1080

IBM Cloud Orchestrator 2.4.0.2: User's Guide

virtual system pattern

One or more virtual images, which can
include script packages, that implement a
deployment topology. A virtual system
pattern is a shared topology definition
used for repeatable deployment.
VM

See virtual machine.




Product Number: 5725-H28

Printed in USA